plesty-sdk 0.3.6__tar.gz → 0.5.0.dev1__tar.gz

{plesty_sdk-0.3.6 → plesty_sdk-0.5.0.dev1}/CHANGELOG.md

@@ -2,6 +2,220 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com).
 
+## [0.5.0.dev1] — 2026-09-25
+
+Development pre-release, the first of the 0.5 line: scaffolds generated against
+plesty-lib 0.5 (`PLESTY_DATA`, `setup.yaml`, `ExperimentCLI`, device preflight) need an SDK that
+writes them before 0.5.0 is ready to be called finished.
+
+### Added
+- **A snapshot is named for the release its line is working towards.**
+  versioningit's default `next_version` bumps the minor, which is wrong on
+  both lines governance#20 runs: six commits after `v0.4.0`, `maintain/0.4`
+  built `0.5.0.dev6`, which sorts *above* the `0.4.1` the line exists to
+  produce, so a bench given that snapshot is never upgraded by the release;
+  and `exp` sitting on `v0.5.0.dev3` built `0.6.0.devN`, a minor nobody is
+  working towards.
+
+  `plesty init` now ships `packaging/versioning.py` and points
+  `[tool.hatch.version.next-version]` at it: `exp` and `main` take the next
+  minor, every other branch the release its last tag precedes — the next
+  patch on `maintain/0.N`. A branch that names no line, including the detached
+  HEAD CI checks out, takes the patch, which understates and so can never
+  shadow a release. A build at a tag is unaffected.
+
+  An existing module takes the same rule with `plesty update --versioning`,
+  which writes the file, adds the block, and annotates `packaging/**` in
+  `REUSE.toml` unless an annotation already covers it — versioningit imports
+  the rule at build time, and the `.pyc` Python writes beside it fails gate 9
+  otherwise. plesty-sdk itself now builds with the rule (plesty-sdk#41).
+- **Every scaffolded device module ships a preflight.** A module installs,
+  configures and serves happily with no instrument behind it: the transport
+  logs that it found nothing, the server binds regardless, and a client can
+  hold a resource against a device that was never there. `plesty init device`
+  now generates `plesty/<module>/preflight.py`, and both entry points call it
+  before touching the instrument — `python -m plesty.<module>` before the
+  server binds, `tests/field_test.py` before a run. It refuses only an
+  instrument the transport looked for and did not find; a transport that
+  cannot tell without opening answers *unknown*, and unknown serves.
+
+  It answers the four questions that were being answered by hand in
+  plesty-k10cr1 and plesty-lightfield-spectrometer: whether the operating
+  system enumerated the instrument and bound a driver, what discovery resolved
+  and what it saw, which `.env` is in effect and whether its server port agrees
+  with the one the fleet handed over as `--tcp-port`, and which version of the
+  module is installed and whether it came from PyPI or a checkout. The
+  transport half is `TrafficManager.preflight()` (plesty-lib#50, >= 0.5.0.dev7);
+  the module reaches it through one author hook, `transport()`, filled in
+  beside `Device.connect()`. `--skip-preflight` serves anyway. The generated
+  `tests/test_preflight.py` mocks the transport, so the logic runs in CI with
+  nothing attached and the module stays over the coverage gate. `summary()` is
+  the only output that may name a serial number; what a report file gets is
+  `to_dict()`, which carries none (plesty-sdk#39).
+
+  `plesty init field-test` reads whether the module has a `preflight.py`: a
+  module scaffolded before this release gets a `preflight()` that says what is
+  missing and lets the run go on, so the generator keeps working on every
+  module the hub already has.
+
+  The `plesty-lib` floor rises to `0.5.0.dev7`, the first whose transports
+  answer `preflight()`.
+- **Gate e3 — Experiment Manifest.** An experiment module now has a run
+  contract to declare (`plesty.lib.experiment.ExperimentCLI`, plesty-lib#54),
+  and nothing enforced it: a module could drift back to a hand-rolled
+  `argparse` and every console offering its settings would silently go empty.
+
+  For `module_type = "experiment"`, `python -m <module> --manifest` must print
+  the declaration as JSON; the gate checks that it names this module, that
+  every configuration parameter carries a `dtype` and a `description` — a
+  control rendered without them is a box with a name on it — and that a
+  bounded parameter carries a `unit`, or its bounds read as bare numbers.
+
+  It then compares the schema with the module's own `config/*.yaml`. A key the
+  configuration sets and the schema omits cannot be edited by anything reading
+  the manifest; a key the schema declares and no configuration sets renders as
+  a setting that does nothing. That drift is the reason the gate exists: a
+  schema nobody keeps current is worse than none, because a console renders it
+  as fact.
+
+- **`plesty init` scaffolds an experiment onto `ExperimentCLI`.** The generated
+  `__main__.py` declares a `Manifest` and a `SCHEMA` matching the scaffolded
+  `config/default.yaml`, and registers a rig builder and an experiment builder
+  in place of its own `argparse` — so a new module passes e3 as scaffolded, and
+  gets `--config`, `--resume`, `--run-root`, `--dry-run` and `--manifest`
+  without writing them. The experiment entry point no longer calls
+  `run_server` itself: `ExperimentCLI.main` does, so the loop pyzmq needs is
+  the library's guarantee rather than something each scaffold must remember.
+
+  The `plesty-lib` floor rises to `0.5.0.dev4`, the first with `ExperimentCLI`.
+- **Gate 8 baselines against the line being built.** It compared the working
+  tree against the newest release of the whole project, which is right only
+  while there is one line. A `maintain/x.y` branch takes fixes to its own
+  features and merges upward only, so it never gains what a later line added:
+  once that line publishes, every function it introduced would read as a
+  removal from the older tree, on every run, for as long as the line is
+  supported. The baseline is now the newest release at or below the tree's own
+  `major.minor`, taken from the line the checkout can reach by tag. Pre-release
+  and yanked files are skipped. Nothing changes on the newest line.
+
+### Fixed
+- **A scaffolded experiment ships the `setup.yaml` plesty-lib requires**
+  (plesty-sdk#43). plesty-lib 0.5.0.dev6 made every experiment module declare
+  its benches and devices in a committed `setup.yaml`; `plesty init experiment`
+  wrote none. It now writes one — `bench-local` with `data: ${LOCAL_DATA}`, a
+  commented remote-bench example, and a `device` entry for the scaffold's
+  `RIG` naming its bench — and `.env.example` suggests the variables it names:
+  `LOCAL_DATA`, empty, so the first real run stops and says to set it, with
+  `DEVICE_ADDRESS` and `PLESTY_DATA` kept as commented overrides for running
+  without a bench. The manifest declares `LOCAL_DATA`. A module scaffolded
+  earlier adds the two files by hand; `hub/experiments/plesty-pol-pl` has a
+  working pair.
+- **A scaffolded experiment names the shared disk the way its library reads
+  it.** plesty-lib 0.5.0.dev6 replaced `PLESTY_DATA_DIR` and
+  `PLESTY_DATA_MOUNT` with one variable, `PLESTY_DATA` — the shared disk as
+  each machine sees it, with every path between machines relative to it — and
+  the scaffold, already pinned above that release, kept writing the two old
+  names into `.env.example` and the manifest. A module scaffolded from it set
+  variables nothing read, so its runs silently went to `./runs` instead of the
+  share. `.env.example`, the manifest and the next steps now carry
+  `PLESTY_DATA`, and the generated `experiment.py` routes a writing device with
+  `set_data_path(self.raw_dir, subdirs=True)` and records its files with
+  `raw_file()`. A module scaffolded earlier migrates by hand: set `PLESTY_DATA`
+  where `PLESTY_DATA_MOUNT` was and drop `PLESTY_DATA_DIR`.
+- **A scaffolded experiment passes its own tests.** When the entry point moved
+  onto `ExperimentCLI`, the generated `tests/test_<module>.py` was not moved
+  with it: it still imported `load_config` and called `build_devices(address)`,
+  neither of which the new `__main__.py` has, so every experiment module failed
+  three of its tests — and gate 7 — as scaffolded. The tests now go through the
+  module's `cli`: `cli.load()` for `--config`, `build_devices(args, config,
+  skip)`, and a `--dry-run` of the shipped `config/default.yaml`. Every project
+  type's generated tests are now run in plesty-sdk's own suite, against the
+  plesty-lib its dev group now requires, the scaffold's own floor
+  (`>=0.5.0.dev7`, was `>=0.3.6`) — tested against an older library, generated
+  code can only fail to import, which is how this went unnoticed.
+- **`plesty init mock-test` runs on a scaffolded device.** Every device module
+  exports `DocDevice = partial(Device, id=...)`, and when no simulator address
+  applies — a fresh scaffold has none — the generated test handed that partial
+  to `DevicePipeline`, which constructs from a class and names it by
+  `__name__`: the test crashed before any gate ran, so gate d1 could not pass.
+  The file now passes `Device` and forwards the partial's own arguments
+  (`DevicePipeline(Device, *DocDevice.args, **DocDevice.keywords)`), the same
+  construction read at run time. A `DocDevice` that is neither a class nor a
+  partial of `Device` is refused with that reason. The probe also rejects a
+  `check_errors()` that returns anything but a list, as gate 7 does, and the
+  device template's stub returns `[]` under the `list[str]` contract
+  plesty-lib declares instead of `None`.
+- The scaffolded analyzer template carries its REUSE header. Every other
+  template declares copyright and licence inline; this one declared nothing, so
+  the file linted as uncovered and its author was credited nowhere — and every
+  project scaffolded from it inherited that gap.
+
+## [0.4.0] — 2026-09-07
+
+A scaffolded device can now be driven by hand. `plesty init device` generates a
+`--gui` entry point that opens the module's control panel — every control built
+from the device schema, nothing hand-written — as an alternative to serving the
+instrument, so a new module is usable at the bench before anyone writes a client
+for it. Qt rides in a `gui` extra, so a headless bench that only ever serves the
+device pays nothing for the window it never opens. Generated projects pin
+`plesty-lib>=0.4.0`, the release `plesty.lib.ui` begins at.
+
+### Added
+- **A scaffolded device offers its control panel.** `plesty init device` now
+  generates `--gui` in the module's `__main__.py`: it opens plesty-lib's
+  `DevicePanel` over a `LocalHandle` on the instrument in this process, as an
+  alternative to serving it — both want the one session the instrument grants,
+  so `main()` does one or the other. Nothing about the window is hand-written;
+  the controls, their bounds, units and tooltips come from the device schema, so
+  a parameter added there appears in the panel.
+
+  The generated `open_panel()` calls `connect()` **before** the panel is built.
+  That ordering is the point of the entry point rather than an implementation
+  detail: what the instrument reports on connection narrows the schema's
+  device-wide envelope to the unit in front of the operator, and those are the
+  bounds worth typing into. On a PM100D the fitted head answers 400–1100 nm
+  against the 185–25000 nm the schema declares for every head.
+
+  Qt lands in a new `gui` extra (`plesty-lib[gui]`), not in `dependencies` — a
+  headless bench serves the device and never opens a window — and the
+  `plesty.lib.ui` import is local to `open_panel`, so serving pulls no toolkit.
+  Every module used to hand-add this entry point; `plesty-pm100d` was the last
+  to do it by hand.
+
+- The device template's note on `kind` now says what declaring `lifecycle` does
+  beyond the field test: an operation whose effect outlives the call is kept off
+  a control panel — the local one and the one a remote client renders. The
+  schema is the only place either can learn it.
+
+### Changed
+- `PLESTY_LIB_VERSION`, the `plesty-lib` floor a scaffold falls back to when
+  PyPI is unreachable, moves `0.3.6` → `0.4.0`. That is the release
+  `plesty.lib.ui` begins at, so it is the floor the generated `--gui` needs;
+  below it the panel path raises `ImportError`. The live PyPI lookup already
+  resolved 0.4.0 on any machine with a route out — this only changes the
+  offline case.
+
+### Fixed
+- **The pre-push hook no longer leaks git's hook variables into the gates.**
+  Git exports `GIT_DIR` and friends into every hook, and everything the hook
+  runs inherits them, so git work nested inside the gates resolves the pushing
+  repository instead of the one it is standing in. The hook now clears them
+  before running `plesty check`; nothing about what the gates check changes.
+
+  Two failures this had already caused. Gate 10 has pip clone each git-pinned
+  dependency into a temp directory, where versioningit read the outer
+  repository's tag and commit — on lightfield_spectrometer (2026-09-04) a
+  pinned `plesty-lib` came out as `0.1.0.dev65+<the module's sha>`, which
+  cannot satisfy the module's own floor, so the audit failed with a resolution
+  error unrelated to the code. That is enough to make anyone drop the pin
+  rather than debug it, and a dropped pin is a module quietly building against
+  the wrong dependency. Separately, a test suite that drives git could commit
+  into the real repository rather than its fixture, which is what made pushing
+  this repo from a worktree unsafe.
+
+  Existing modules keep the old hook until `plesty init` is re-run; the fix is
+  a one-line `unset` in `.git/hooks/pre-push` for anyone who does not want to.
+
 ## [0.3.6] — 2026-09-03
 
 Everything the scaffolds generate now passes the gates the scaffolds ask for.

{plesty_sdk-0.3.6 → plesty_sdk-0.5.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-sdk
-Version: 0.3.6
+Version: 0.5.0.dev1
 Summary: Command-line application for developing Python modules compliant with the Plesty standard.
 Author: Plesty Development Team, Yunshuang Yuan, Christopher Borchers, fvrehlinger, Maximilian Heller, Michael Zopf
 License-Expression: LGPL-3.0-or-later
@@ -55,10 +55,14 @@ plesty init device --author "Jane Doe" --email jane@example.com
 
 # 2. Develop your module — the pre-push hook runs compliance checks automatically
 
-# 3. Run the full [SDK] compliance check manually at any time
+# 3. Drive the instrument from a control panel built out of your device schema
+uv sync --extra gui
+python -m plesty.power_meter --gui
+
+# 4. Run the full [SDK] compliance check manually at any time
 plesty check
 
-# 4. Preview the documentation locally
+# 5. Preview the documentation locally
 plesty docs serve
 ```
 

{plesty_sdk-0.3.6 → plesty_sdk-0.5.0.dev1}/README.md

@@ -23,10 +23,14 @@ plesty init device --author "Jane Doe" --email jane@example.com
 
 # 2. Develop your module — the pre-push hook runs compliance checks automatically
 
-# 3. Run the full [SDK] compliance check manually at any time
+# 3. Drive the instrument from a control panel built out of your device schema
+uv sync --extra gui
+python -m plesty.power_meter --gui
+
+# 4. Run the full [SDK] compliance check manually at any time
 plesty check
 
-# 4. Preview the documentation locally
+# 5. Preview the documentation locally
 plesty docs serve
 ```
 

{plesty_sdk-0.3.6 → plesty_sdk-0.5.0.dev1}/REUSE.toml

@@ -37,3 +37,11 @@ path = [
 SPDX-FileCopyrightText = "2025-2026 Plesty Development Team"
 SPDX-FileContributor = "Yunshuang Yuan"
 SPDX-License-Identifier = "LGPL-3.0-or-later"
+
+# versioningit imports `packaging/versioning.py` at build time, so Python
+# writes a `.pyc` beside it that `reuse lint` sees even though `.gitignore`
+# hides it from git.
+[[annotations]]
+path = ["packaging/**"]
+SPDX-FileCopyrightText = "2026 Plesty Development Team"
+SPDX-License-Identifier = "LGPL-3.0-or-later"

{plesty_sdk-0.3.6 → plesty_sdk-0.5.0.dev1}/docs/architecture.md

@@ -17,9 +17,9 @@ into five areas:
 ```{mermaid}
 graph TD
     CLI["CLI layer<br/>cli.py · context.py"]
-    CHECK["Check engine<br/>commands/check.py · authorship.py"]
+    CHECK["Check engine<br/>commands/check.py · authorship.py · semver.py · report.py"]
     DOCS["Docs builder<br/>commands/docs/*"]
-    SCAFFOLD["Scaffolding<br/>commands/init.py · commands/update.py"]
+    SCAFFOLD["Scaffolding<br/>commands/init.py · update.py · field_test.py · mock_test.py"]
     LICENSE["Licensing<br/>commands/license.py"]
     MANUAL["Manuals<br/>commands/manual.py"]
     ASSETS["Packaged assets<br/>assets/*"]
@@ -39,9 +39,9 @@ graph TD
 | Area | Modules | Responsibility |
 |---|---|---|
 | CLI layer | `cli.py`, `context.py` | Click command group; resolves `--project-dir` into an `ApplicationContext` that lazily parses `pyproject.toml` and derives `DocumentationSettings`. Every command receives this context — no command parses `pyproject.toml` itself. |
-| Check engine | `commands/check.py`, `authorship.py` | The compliance gates behind `plesty check`. Each gate is a plain function raising `click.ClickException` (or exiting with the failing tool's code) on violation. `authorship.py` holds the git-history authorship analysis shared with `plesty license author`. |
-| Docs builder | `commands/docs/` (`serve.py`, `deploy.py`, `sphinx_builder.py`, `generate.py`) | Sphinx configuration and build (`sphinx_builder.py`), live-reload preview (`serve`), pages-branch deployment with versioned releases (`deploy`), and zero-effort device reference-page generation from a live `doc_model()` (`generate.py`). `cache.py` maintains the git-ignored `.plesty/` build cache used by `serve`. |
-| Scaffolding | `commands/init.py`, `commands/update.py` | Project generation from the copier template (`plesty init`) and in-place maintenance of existing projects (`plesty update`). `update` reuses `init`'s CI-generation and hook-installation helpers so both commands emit identical artifacts. |
+| Check engine | `commands/check.py`, `authorship.py`, `semver.py`, `report.py` | The compliance gates behind `plesty check`. Each gate is a plain function raising `click.ClickException` (or exiting with the failing tool's code) on violation. `authorship.py` holds the git-history authorship analysis shared with `plesty license author`; `semver.py` the public-API diff against the published release for gate 8; `report.py` the `reports/check.json` document every run writes. |
+| Docs builder | `commands/docs/` (`serve.py`, `deploy.py`, `sphinx_builder.py`, `generate.py`, `picker.py`) | Sphinx configuration and build (`sphinx_builder.py`), live-reload preview (`serve`), pages-branch deployment with versioned releases (`deploy`), zero-effort device reference-page generation from a live `doc_model()` (`generate.py`), and stamping the version picker into release trees built before it existed (`picker.py`). `cache.py` maintains the git-ignored `.plesty/` build cache used by `serve`. |
+| Scaffolding | `commands/init.py`, `commands/update.py`, `commands/field_test.py`, `commands/mock_test.py`, `tui.py` | Project generation from the copier template (`plesty init`) and in-place maintenance of existing projects (`plesty update`). `update` reuses `init`'s CI-generation and hook-installation helpers so both commands emit identical artifacts. `field_test.py` and `mock_test.py` generate a device module's field test and mock pipeline test (`plesty init field-test` / `mock-test`); `tui.py` is the dependency-free checkable list the field-test interview uses. |
 | Licensing and manuals | `commands/license.py`, `commands/manual.py` | SPDX header maintenance via the REUSE tool, and Markdown/PDF manual generation for external (non-hub) device packages. |
 | Packaged assets | `plesty/sdk/assets/` | Data shipped inside the wheel: the canonical `ruff.toml`, the copier scaffold under `templates/`, the shared Sphinx theme (`hub-theme/`), and the pages-branch CI file (`docs-build-gitlab-ci.yml`). Assets are always accessed through `importlib.resources`, never by path relative to the source tree. |
 
@@ -92,11 +92,11 @@ engine is re-run by CI (`hub-check` in the `plesty-standard-ci` component) as th
 authoritative final gate. Gates carry a tier label:
 
 - **`[SDK+CI]`** (gates 1–10) — enforced locally and repeated in CI.
-- **`[SDK]`** (gate 11, docs build) — local-only. When `CI=true` (set on every GitLab
-  runner) gate 11 reports itself skipped, because the dedicated `hub-deploy-docs` CI job
-  builds the docs instead. Tests exercising the Sphinx path must therefore clear the `CI`
-  variable.
-- **`[Device]` / `[Analyzer]` / `[Experiment]`** (d1–d3, a1, e1–e2) — module-type gates,
+- **`[SDK]`** (gate 11, docs build) — runs locally and in merge-request pipelines. In a
+  branch pipeline (`CI=true` without `CI_PIPELINE_SOURCE=merge_request_event`) gate 11
+  reports itself skipped, because the dedicated `hub-deploy-docs` CI job builds the docs
+  instead. Tests exercising the Sphinx path must therefore clear the `CI` variable.
+- **`[Device]` / `[Analyzer]` / `[Experiment]`** (d1–d3, a1, e1–e3) — module-type gates,
   active only when `[tool.plesty] module_type` is `"device"`, `"analyzer"`, or
   `"experiment"` respectively; every other module type gets an explicit "N/A" line, so
   the gate list is identical everywhere and activation is declarative, never heuristic.
@@ -104,7 +104,9 @@ authoritative final gate. Gates carry a tier label:
   return-annotation contract, d3 that the device renders a populated `doc_model()`;
   a1 verifies the five `AnalyzerPipeline` contract tests; e1 verifies the five
   `ExperimentPipeline` contract tests, e2 that persistence goes through the unified
-  data layer.
+  data layer, e3 that `python -m <module> --manifest` publishes the run contract and
+  that its configuration schema and the module's own `config/*.yaml` say the same
+  thing.
 
 The standard selects how deep the run goes: `pixel` runs gates 1–2, `nebula` gates 1–6
 (static, no network), `quantum` everything including the module-type gates. The full
@@ -161,14 +163,24 @@ tradeoff is losing pydata-specific features (notably its version switcher UI); v
 now surfaced through Sphinx's plain `version`/`release` fields and the deploy-side
 `versions.json`.
 
-**Schema-usage enforcement inside the data-layer gate.** Gate 4 statically rejects classes
-that shadow a plesty-lib schema model (`DeviceStatus`, `ResultDocument`, `Plan`, …), and
-gates d2/e2 enforce the telemetry annotations and `save_result` persistence path. The
-alternative — trusting convention and review — had already produced silent forks of the
-data contract. AST-based enforcement is cheap, runs offline in the pre-push hook, and needs
-no imports of the target package; the tradeoff is that static analysis can only catch what
-it can resolve (e.g. a dynamically computed `open()` mode is deliberately left alone), so
-the gates are a floor, not a proof.
+**Schema-usage enforcement inside the data-layer gate.** plesty-lib defines the data every
+module exchanges — a device's configuration and operations, its status and telemetry, an
+experiment's plan and journal, a stored result — as a fixed set of classes (the *schema
+models*). A module that wrote its own class of the same name — its own `DeviceStatus`, say —
+would *shadow* the library's: code in that module would silently use the local copy, which
+no other module, console or reader understands. Gate 4 therefore scans every Python file
+under `plesty/<module>/` of **every** module type — device, analyzer, experiment and core
+alike — and fails on a class definition whose name is one of plesty-lib's schema models
+(`ConfigParameter`, `FuncMeta`, `DeviceStatus`, `TelemetryEvent`, `ResultDocument`, `Plan`,
+`Journal`, … — the full list is `_PROTECTED_SCHEMA_NAMES` in `commands/check.py`), and on a
+public function without a return type annotation. Two further checks apply to one module
+type each: gate d2 (devices) requires `status()` to be annotated `DeviceStatus`, and gate e2
+(experiments) requires results to be stored through `save_result` rather than written by
+hand. The alternative — trusting convention and review — had already produced silent forks
+of the data contract. Reading the source as a syntax tree, without importing it, is cheap,
+runs offline in the pre-push hook, and cannot be fooled by a module that fails to import;
+the tradeoff is that such a check sees only what is written literally (a file mode computed
+at run time is deliberately left alone), so the gates are a floor, not a proof.
 
 **Generated device documentation (gate d3) over hand-written reference pages.**
 Hand-written parameter and operation tables drift the moment a schema changes. Rendering
@@ -187,6 +199,44 @@ have already diverged. The cost is a coupling to the component's ref and input c
 a rename or ref change in plesty-ci breaks scaffolds (see technical debt below) — which we
 accept because centralised evolution has proven far cheaper than fleet-wide file surgery.
 
+**A generated device carries its own control panel, with Qt in an extra.** The panel is
+plesty-lib's `DevicePanel`, and it reaches a device only through a four-call interface,
+`DeviceHandle` — `describe()`, `query()`, `write()`, `call()`. Where the device is decides
+only which handle the panel is given: in the same process, the device object wrapped in a
+`LocalHandle`; over the network, a TCP client (`DeviceTCPIPClient`) satisfies the same
+interface; from a remote `plesty-bench`, the bench agent relays the same four calls. So
+the one panel drives a device locally or remotely alike. What the scaffold generates is the
+local case: `--gui` on the module's existing entry point opens the panel on the machine the
+instrument is plugged into, rather than shipping a separate console or leaving each module
+to hand-write one.
+
+`--gui` and serving are alternatives *within one process*: both open the instrument, and
+most instruments grant a single session, so `python -m plesty.<module>` does one or the
+other. Both at once is the remote case — serve the device, and open the panel from a client
+on the same or another machine.
+
+The controls are built from `describe()`, the device's schema serialized as plain data, so
+a module gets a usable window the moment its schema is right, and a hole in that payload
+surfaces at the bench instead of only across a network. Operations are filtered by their
+declared `kind`, which makes the schema the single place that decides what a panel offers,
+local or remote.
+
+A module with a GUI of its own is not overridden by anything: `--gui` is ordinary generated
+code in the module's `__main__.py` (`open_panel()`), and the module replaces it — with its
+own `Panel` subclass, several panels in one window, or no panel — by editing that function.
+Nothing loads a module's panel code from elsewhere.
+
+Qt lives in a generated `gui` extra rather than in the generated `dependencies` — a headless
+bench serves the device and never opens a window — which is why `plesty.lib.ui` is imported
+inside the panel path and not at module scope. How far Qt reaches is deliberately bounded:
+the panel contract (`Panel`), the device handle, the worker thread that keeps device calls
+off the window's thread, and the `describe()` payload import no toolkit; Qt is confined to
+`plesty.lib.ui.qt` and to the widget each panel builds. Moving to another toolkit, or
+offering a second kind of interface such as a web page, would therefore mean new widget
+code and a new shell, while the data a panel renders and the way it reaches a device stay
+as they are. The tradeoff is that this widget code is Qt today, and a second toolkit would
+be a second implementation of it rather than a switch.
+
 **`plesty update --install-hook` for cloned projects.** Git hooks live in `.git/` and are
 never cloned, so `plesty init`'s pre-push hook silently vanishes for every contributor
 after the first. Rather than adopting a hook-manager dependency (pre-commit) or committing
@@ -216,6 +266,8 @@ The sanctioned runtime dependencies (from `[project] dependencies` in `pyproject
 | `sphinxcontrib-mermaid` | Mermaid diagrams in docs (including this page). |
 | `livereload` / `watchfiles` | Local preview server and rebuild-on-change for `plesty docs serve`. |
 | `md2pdf` | PDF rendering for `plesty manual generate --with-pdf`. |
+| `griffe` | Static public-API extraction for the gate 8 diff — the analyzed package is never imported. |
+| `packaging` | Version and specifier parsing (gate 8 baselines, `--lib-version`, versioned docs deploy). |
 | `pyside6-essentials` (extra: `gui`) | Optional GUI support; not installed by default. |
 
 **Policy:** a new third-party library may only be added if it is actively maintained
@@ -231,11 +283,4 @@ as a GitLab issue labeled
 [`type::debt`](https://gitlab.com/plesty/core/plesty-sdk/-/issues/?label_name%5B%5D=type%3A%3Adebt)
 — per the
 [governance DoD](https://gitlab.com/plesty/governance/-/blob/main/CONTRIBUTING.md),
-permanent architectural debt is filed before the shortcut lands. Two standing caveats
-matter when reading the gate architecture above: gate 11 (docs build) never runs in
-merge-request pipelines — the zero-warning build is enforced by the pre-push hook and,
-post-merge, by `hub-deploy-docs`
-([sdk#22](https://gitlab.com/plesty/core/plesty-sdk/-/issues/22)) — and the authoritative
-CI-side semantic-versioning API diff that gate 8 defers to does not exist yet, so version
-enforcement is advisory
-([plesty-ci#10](https://gitlab.com/plesty/core/plesty-ci/-/issues/10)).
+permanent architectural debt is filed before the shortcut lands.

{plesty_sdk-0.3.6 → plesty_sdk-0.5.0.dev1}/docs/commands/check.md

@@ -39,8 +39,9 @@ Gates are divided into two tiers depending on where they are enforced:
 
 - **`[SDK+CI]`** — enforced locally by `plesty check` and repeated by CI in a clean
   environment as the authoritative final gate (gates 1–10).
-- **`[SDK]`** — enforced locally only; skipped in CI (`CI=true`). Currently just the
-  Docs Build gate (11), which CI covers with its dedicated `hub-deploy-docs` job.
+- **`[SDK]`** — enforced locally and in merge-request pipelines; skipped in branch
+  pipelines, where the dedicated `hub-deploy-docs` job builds the docs instead. Currently
+  just the Docs Build gate (11).
 
 The pre-push git hook installed by `plesty init` runs `plesty check` before every push,
 enforcing whichever standard resolves for the project (see Standard resolution above).
@@ -75,10 +76,10 @@ release. Required for every PyPI release, and the derived default from version `
 | Gate | Tier | What is checked |
 |---|---|---|
 | Automated Test Coverage | `[SDK+CI]` | `pytest --cov` with a minimum threshold of **80%** |
-| Semantic Versioning | `[SDK+CI]` | Reminder to tag a new release when commits exist since the last tag; API-level diff against the published PyPI release runs in CI |
+| Semantic Versioning | `[SDK+CI]` | Diffs the public API against the newest PyPI release on the tree's own `major.minor` line (so a `maintain/0.N` branch is compared with `0.N`, not with a later line) and requires a version bump that matches: a minor bump for a breaking change before `1.0.0`, a major bump from then on. Advisory locally, fails in CI. When the package is unpublished or PyPI is unreachable, falls back to a reminder to tag a release when commits exist since the last tag |
 | Licensing Compliance | `[SDK+CI]` | [REUSE](https://reuse.software/) compliance (`reuse lint`) and authorship currency of the SPDX headers; `license` field declared in `pyproject.toml` |
 | Vulnerability Audit | `[SDK+CI]` | No known CVEs in declared dependencies; queries the OSV database via `pip-audit` |
-| Docs Build | `[SDK]` | Full Sphinx build must complete with zero errors and zero warnings. Local-only — skipped in CI (`CI=true`), where the dedicated `hub-deploy-docs` job builds the docs |
+| Docs Build | `[SDK]` | Full Sphinx build must complete with zero errors and zero warnings. Runs locally and in merge-request pipelines, so a docs-breaking change fails before it merges; skipped in branch pipelines, where the dedicated `hub-deploy-docs` job builds the docs |
 
 ### Module-type gates
 
@@ -93,6 +94,7 @@ they report N/A for every other module type.
 | a1 — Analyzer Contract | `module_type = "analyzer"` | The five `AnalyzerPipeline` contract gate tests (`plesty.lib.test.analyzer_pipeline`) are present in `tests/` and pass on schema-generated synthetic inputs: public `Analyzer` subclass, schema integrity, analyze-signature match, mock round-trip, provenance stamp |
 | e1 — Experiment Contract | `module_type = "experiment"` | The five `ExperimentPipeline` contract gate tests (`plesty.lib.test.experiment_pipeline`) are present in `tests/` and pass: public `Experiment` subclass, deterministic `build_plan()`, resolvable step ops, JSON-serializable plan, async lifecycle hooks |
 | e2 — Experiment Persistence | `module_type = "experiment"` | No ad-hoc persistence in the module package (`np.save`/`np.savez`, `pickle.dump`, `h5py.File`/`open` with write mode) — results are persisted via `plesty.lib.data.save_result`/`ResultDocument` |
+| e3 — Experiment Manifest | `module_type = "experiment"` | `python -m <module> --manifest` prints the run contract (`plesty.lib.experiment.Manifest`): it names this module, every configuration parameter carries a `dtype` and a `description` (and a `unit` where it is bounded), and the schema and the module's own `config/*.yaml` declare the same keys — a key only one of them knows about is either uneditable or a setting that does nothing |
 | f1 — Field Test Findings | any module with a published field test report | No `reports/<instrument>/field-test.json` holds an `error` finding — a parameter the instrument refuses or will not answer, which the module nonetheless declares |
 
 ## Report artifacts

{plesty_sdk-0.3.6 → plesty_sdk-0.5.0.dev1}/docs/commands/docs.md

@@ -46,7 +46,7 @@ whenever a `.md` or `.rst` file changes. Useful during active documentation writ
 
 | Option | Default | Description |
 |---|---|---|
-| `--dev-addr` | `127.0.0.1:8000` | Host and port for the preview server |
+| `--dev-addr` | `localhost:8000` | Host and port for the preview server |
 
 ### Example
 
@@ -84,19 +84,19 @@ yet exist.
 ```bash
 # Deploy development snapshot (latest)
 plesty docs deploy \
-  https://gitlab-ci-token:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
+  https://oauth2:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
   docs-build \
   --latest
 
 # Deploy a versioned release
 plesty docs deploy \
-  https://gitlab-ci-token:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
+  https://oauth2:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
   docs-build \
   --release
 ```
 
-In practice this command is called by the `deploy-docs` CI component and does not need to
-be run manually.
+In practice this command is called by the `hub-deploy-docs` job of the `plesty-standard-ci`
+component and does not need to be run manually.
 
 ---