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

{plesty_sdk-0.5.0.dev1 → plesty_sdk-0.5.1}/.gitlab-ci.yml

@@ -2,9 +2,10 @@ workflow:
   rules:
     # Create pipelines for merge requests
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-    # Create branch pipelines for main and exp
+    # Create branch pipelines for main, exp and every supported maintain/* line
     - if: $CI_COMMIT_BRANCH == "main"
     - if: $CI_COMMIT_BRANCH == "exp"
+    - if: $CI_COMMIT_BRANCH =~ /^maintain\//
     # Create pipelines for tags (dev and stable releases)
     - if: $CI_COMMIT_TAG
     # Otherwise do not create a pipeline

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

@@ -2,6 +2,34 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com).
 
+## [0.5.1] — 2026-10-15
+
+Fixes on the 0.5 line, the same as in 0.4.1. Supported lines: 0.5 and 0.4
+(`maintain/0.4`).
+
+### Fixed
+- The logo in the generated docs pages no longer animates forever. The photon
+  in the PLESTY mark looped indefinitely through a blur filter, so an idle docs
+  page kept the browser redrawing every frame (~25% CPU in Safari). It now
+  travels three times and stops.
+
+### Security
+- urllib3 2.8.0 and tornado 6.5.10 in the lockfile: 2.7.0 and 6.5.8 carry six
+  published advisories (PYSEC-2026-4175/4176/4177, GHSA-chx6-46f5-w4vp,
+  GHSA-c2m8-h5v5-343r, GHSA-3hv7-mjh2-fv65), which failed the audit gate.
+
+## [0.5.0] — 2026-09-29
+
+Opens the 0.5 line, scaffolding against the released plesty-lib 0.5.0: every
+change listed under 0.5.0.dev1 below, and the pin that follows. Supported
+lines: 0.5 and 0.4 (`maintain/0.4`); 0.3 is retired.
+
+### Changed
+- **Scaffolds pin the released plesty-lib 0.5.0, not a snapshot.** The floor
+  `plesty init` writes when PyPI cannot be reached (`PLESTY_LIB_VERSION`), the
+  version a scaffolded device's preflight names when its library is too old,
+  and the dev-group pin are `0.5.0`, where they named `0.5.0.dev7`.
+
 ## [0.5.0.dev1] — 2026-09-25
 
 Development pre-release, the first of the 0.5 line: scaffolds generated against
@@ -98,6 +126,17 @@ writes them before 0.5.0 is ready to be called finished.
   `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.
 
+### Added
+- **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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-sdk
-Version: 0.5.0.dev1
+Version: 0.5.1
 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

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

@@ -124,17 +124,10 @@ needs network access (OSV queries), so pushing requires connectivity under `quan
 ### Version-derived default standard
 
 When `[tool.plesty] standard` is unset, `derive_standard()` maps the release version to a
-level, so shared prototypes ramp up automatically:
-
-| Version | Standard |
-|---|---|
-| `< 0.1.0`, or a dynamic version with no release tag yet | `pixel` |
-| `>= 0.1.0, < 1.0.0` | `nebula` |
-| `>= 1.0.0` | `quantum` |
-
-An explicit `standard` always wins; a project with no version information at all falls back
-to `quantum`, the conservative default. `plesty check` echoes which rule applied, so the
-resolution is never silent.
+level, so shared prototypes ramp up automatically — pixel before `0.1.0`, nebula before
+`1.0.0`, quantum from then on. The mapping and its fallbacks are specified once, under
+[Standard resolution](commands/check.md#standard-resolution) on the `plesty check` page.
+`plesty check` echoes which rule applied, so the resolution is never silent.
 
 ## Design Decisions
 

plesty_sdk-0.5.1/docs/commands/init-field-test.md

@@ -0,0 +1,128 @@
+# plesty init field-test
+
+Adds a field test — the gate sequence run against the real instrument — to an
+**existing** device module. Unlike [`plesty init mock-test`](init-mock-test.md),
+it interviews you.
+
+```bash
+cd plesty-pm100d
+plesty init field-test          # interactive
+plesty init field-test --force  # replace an existing tests/field_test.py
+```
+
+`plesty.lib.test.field_test.FieldTestPipeline` gives every module the same gate
+sequence. The gates are the easy part — they are generic and already shared.
+What takes the time, and what three modules each got wrong at least once, is
+the **configuration**, because every line of it is a judgement about the
+instrument that no schema inspection can make:
+
+- which operations are safe to call unattended — the wrong answer moved a
+  stage, fired an exposure, and rewrote a sensor's zero calibration
+- which parameters survive being written back their own value — one crashed
+  the controlling application outright, killing every call after it
+- what is slow enough to be timed out on demand, since a call returning in two
+  milliseconds cannot be abandoned and its gate silently skips
+- which two parameters are distinguishable enough that a stale reply is
+  unambiguous
+- whether connecting is cheap, or starts an application and costs half a minute
+
+## Candidates from the device, judgement from you
+
+So the command asks the **device** for the *candidates*, and you for the
+*judgement*. It constructs the module hardware-free — exactly as `plesty docs`
+does, which gate d3 already requires — and reads `doc_model()`.
+
+Not the JSON schema files, and the difference is not cosmetic. A module
+registers parameters and operations in Python too (`register_config` in
+`__init__`, an `@expose_to_api` method), and none of that is in a file:
+`plesty-pm100d` alone has two such operations, which a file-reading generator
+would never offer. And for a grouped schema the keys differ —
+`get_config_list()` answers `group_prefix.param_key` while the file is keyed by
+the bare name, so an `only_keys` list built from the file would name parameters
+the pipeline cannot resolve. That is the group-name against command-prefix
+mismatch three modules hit independently.
+
+There is no fallback to the files. A device module that cannot build its doc
+model already fails gate d3, and generating from a partial picture would
+produce a file that looks complete and tests less than it claims.
+
+## The interview
+
+Each question states what the answer is used for before offering the choices,
+and each answer is followed by "why?" — the reason is written into the
+generated file as a comment, so the next reader sees why and not only what.
+
+Choices are a checkable list: arrow keys move, space selects, `a` selects all,
+`n` clears, Enter confirms, Escape backs out. Each entry shows what it is —
+a parameter's type and range, an operation's description — because choosing
+which operations may run unsupervised from a list of bare names is how the
+wrong one gets picked.
+
+Nothing is ticked to begin with, and Enter confirms whatever *is* ticked, so
+the cheapest keypress gives the most conservative answer. `a` exists but has
+to be typed. While a list is empty it says what empty means **for that
+question**, which is not the same everywhere: no operation selected means none
+is called, while no parameter selected means every one is written back.
+
+A run with no keyboard — piped input, a script, CI — falls back to typing
+comma-separated numbers rather than waiting for a keypress that never comes.
+
+**Nothing unclassified is treated as safe.** An operation you do not select is
+in neither list: it is never called, and the gate that would have called it
+skips saying so. A generated allow-list that quietly included a motion command
+would be worse than no generator at all.
+
+**What the module declares is not asked again.** An operation exposed with a
+kind — `@expose_to_api(kind="motion", position_key="MO.Position", step=1.0)`,
+`kind="lifecycle"`, `kind="control"`, or a `"kind"` block in
+`schema_func.json` (plesty-lib#39) — is shown as `[motion]`, `[lifecycle]`,
+`[control]` in the chooser, and the "acts on the world" question is asked only
+about operations that declared nothing. A `configure` operation is not offered
+at all: it is recorded as excluded, because a setting that outlives the call is
+verified by the round-trip gate. For an allow-listed motion the interview
+confirms how far the test may move it (`step`; the declared value is the
+default) and, if the module left it open, which parameter reports the position
+— a motion with neither is dropped, since the pipeline drives a motion one step
+out from that parameter and back and will not guess how far. A motion chosen as
+the slow operation is asked only how far the long move goes: the pipeline
+starts it from wherever the part is and moves it back afterwards. Both
+generated files carry the result as `OP_KINDS`.
+
+## The generated files
+
+The result is two files from one interview. `tests/field_test.py` runs on the
+bench against the instrument: hardware-gated (it defines no pytest test
+functions, so CI collects nothing), wired to publish
+`reports/<instrument>/field-test.json`, and runnable against the simulator
+first:
+
+```bash
+uv run python tests/field_test.py --address mock
+uv run python tests/field_test.py --address <address>
+```
+
+`tests/field_test_client.py` runs the same checks over the wire, against the
+served module. It inherits the answers rather than asking again: an operation
+unsafe on the bench is unsafe over the network too, and a second allow-list
+would be a second chance to disagree.
+
+Neither file is replaced without `--force`: they hold answers somebody thought
+about, and a hardware run may since have corrected them.
+
+## The answers are kept
+
+Each answer is written to `.plesty/field-test.json` as it is given, and every
+run of the command starts from what that file holds — so Ctrl-C loses nothing,
+and running `plesty init field-test` again carries on from where the interview
+stopped. A question that was displayed but not answered is asked again; it is
+marked done only once an answer is in hand. The file is the source of truth:
+edit it to change an answer without repeating the interview, because an answer
+hand-edited in the generated `.py` is overwritten by the next run. Answers left
+by an older SDK in `.plesty-field-test.partial.json` are moved into `.plesty/`
+on the first run.
+
+The run ends by saying which constant holds which answer.
+
+The interview text ships in the wheel
+(`plesty/sdk/assets/init/field-test-questions.yaml`) and the generated file's
+skeleton alongside it (`field-test.py.template`).

plesty_sdk-0.5.1/docs/commands/init-mock-test.md

@@ -0,0 +1,86 @@
+# plesty init mock-test
+
+Adds the hardware-free test gate d1 requires to an **existing** device module.
+Unlike [`plesty init field-test`](init-field-test.md), it asks nothing.
+
+```bash
+cd plesty-pm100d
+plesty init mock-test          # writes tests/test_mock_pipeline.py
+plesty init mock-test --force  # regenerate over its own previous output
+```
+
+The field-test interview exists because every one of its questions is a safety
+judgement about a real instrument. Nothing in the mock pipeline can move a
+stage or fire an exposure, and everything it needs is either declared by the
+device or settled by trying it:
+
+| Source | What it gives |
+|---|---|
+| the device's `doc_model()` | the parameters and operations, read through the same reader the field test uses |
+| the package name | the module and the import |
+| a construction probe | how to reach the device without hardware |
+
+## The probe
+
+**The probe is the design.** A device module is hardware-free in one of
+several ways — `address="mock"` selects an in-memory simulator in one
+reference module, `use_mock_solver=True` does it in the other — and which one
+applies is knowable by constructing the device and looking. Each candidate is
+verified *the way the gates will verify it*: connect, read `is_operatable`,
+call `identity()`, and call `check_errors()`, which must return a list — empty
+on a fresh device. A strategy is written into the file only once it has passed
+the checks the file will make, which is why a generated test that gets written
+is a generated test that passes those checks.
+
+When neither applies, the last resort is the module's own `DocDevice` — the
+hardware-free construction gate d3 already requires. A module scaffolded by
+`plesty init device` exports it as `partial(Device, id=...)`, and because
+`DevicePipeline` constructs from a class, the file passes `Device` and
+forwards the partial's own arguments:
+
+```python
+PIPELINE = DevicePipeline(Device, *DocDevice.args, **DocDevice.keywords)
+```
+
+A `DocDevice` that is neither a class nor a partial of `Device` is refused
+with that reason.
+
+Where no strategy works the command refuses and lists what it tried. It does
+not fall back to asking: a developer handed a question the probe could not
+answer would be guessing at the same thing, and a file built on a guess looks
+complete and tests less than it claims. Give the device a hardware-free path —
+`address="mock"` is the convention, and
+`plesty.lib.sim.demo_device.DemoDevice` is the reference implementation of it —
+then run the command again.
+
+The probe covers three of the eight gates. On a fresh scaffold the file is
+written and gate 2 (parameter key resolution) still fails until the device
+declares its schema — the first of the next steps `plesty init device` prints.
+
+## The generated file
+
+The generated file is short, because `run_mock_pipeline()` runs all eight
+gates and raises with everything that failed:
+
+```python
+from plesty.lib.test.device_pipeline import DevicePipeline
+
+from plesty.pm100d import Device
+
+PIPELINE = DevicePipeline(Device, address="mock")
+
+
+def test_mock_pipeline() -> None:
+    """Run the eight mock gates and fail with everything that broke."""
+    PIPELINE.run_mock_pipeline()
+```
+
+No schema path appears in it. The gates read what the device declares at run
+time, so nothing here restates a schema and nothing goes stale when the device
+gains a parameter.
+
+The file is always `tests/test_mock_pipeline.py`, never `tests/test_<module>.py`
+— that is where a module's hand-written unit tests already live, and one
+reference module keeps 487 lines of them. `--force` regenerates over this
+command's own output and refuses anything else, checked by a marker in the
+file, so a regeneration cannot destroy work.

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

@@ -19,8 +19,9 @@ plesty init [PROJECT_TYPE] [OPTIONS]
 and `experiment` the plan/journal experiment skeleton with the E1 gate tests.
 
 Two further types, `mock-test` and `field-test`, add a test to an **existing** device
-module instead of creating a project — see [`plesty init mock-test`](#plesty-init-mock-test)
-and [`plesty init field-test`](#plesty-init-field-test).
+module instead of creating a project; each has its own page:
+[`plesty init mock-test`](init-mock-test.md) and
+[`plesty init field-test`](init-field-test.md).
 
 ## Naming conventions
 
@@ -63,9 +64,10 @@ After copying the template, `plesty init` automatically:
 2. **Creates the initial git commit** — required by `versioningit` to resolve a package
    version from git history.
 3. **Installs the pre-push hook** — writes `.git/hooks/pre-push` to run
-   `plesty check` automatically before every `git push` (standard read from
-   `[tool.plesty] standard` in `pyproject.toml`, or derived from the release
-   version when unset — `<0.1.0` pixel, `<1.0.0` nebula, `>=1.0.0` quantum).
+   `plesty check` automatically before every `git push`, at the project's
+   resolved standard (see [Standard resolution](check.md#standard-resolution)).
+   Hooks are not cloned: a contributor who clones the project installs it once
+   with `plesty update --install-hook`.
 
 ## Examples
 
@@ -316,188 +318,3 @@ the global `--quiet` flag to print only the result line:
 ```bash
 plesty --quiet --project-dir plesty-foo-bar init device
 ```
-
-## `plesty init mock-test`
-
-Adds to an **existing** device module, like `field-test` — and unlike it, asks
-nothing.
-
-```bash
-cd plesty-pm100d
-plesty init mock-test          # writes tests/test_mock_pipeline.py
-plesty init mock-test --force  # regenerate over its own previous output
-```
-
-The field-test interview exists because every one of its questions is a safety
-judgement about a real instrument. Nothing in the mock pipeline can move a
-stage or fire an exposure, and everything it needs is either declared by the
-device or settled by trying it:
-
-| Source | What it gives |
-|---|---|
-| the device's `doc_model()` | the parameters and operations, read through the same reader the field test uses |
-| the package name | the module and the import |
-| a construction probe | how to reach the device without hardware |
-
-**The probe is the design.** A device module is hardware-free in one of
-several ways — `address="mock"` selects an in-memory simulator in one
-reference module, `use_mock_solver=True` does it in the other — and which one
-applies is knowable by constructing the device and looking. Each candidate is
-verified *the way the gates will verify it*: connect, read `is_operatable`,
-call `identity()` and `check_errors()`. A strategy is written into the file
-only once it has passed the checks the file will make, which is why a
-generated test that gets written is a generated test that passes.
-
-Where no strategy works the command refuses and lists what it tried. It does
-not fall back to asking: a developer handed a question the probe could not
-answer would be guessing at the same thing, and a file built on a guess looks
-complete and tests less than it claims. Give the device a hardware-free path —
-`address="mock"` is the convention, and
-`plesty.lib.sim.demo_device.DemoDevice` is the reference implementation of it —
-then run the command again.
-
-The generated file is short, because `run_mock_pipeline()` runs all eight
-gates and raises with everything that failed:
-
-```python
-from plesty.lib.test.device_pipeline import DevicePipeline
-
-from plesty.pm100d import Device
-
-PIPELINE = DevicePipeline(Device, address="mock")
-
-
-def test_mock_pipeline() -> None:
-    """Run the eight mock gates and fail with everything that broke."""
-    PIPELINE.run_mock_pipeline()
-```
-
-No schema path appears in it. The gates read what the device declares at run
-time, so nothing here restates a schema and nothing goes stale when the device
-gains a parameter.
-
-The file is always `tests/test_mock_pipeline.py`, never `tests/test_<module>.py`
-— that is where a module's hand-written unit tests already live, and one
-reference module keeps 487 lines of them. `--force` regenerates over this
-command's own output and refuses anything else, checked by a marker in the
-file, so a regeneration cannot destroy work.
-
-## `plesty init field-test`
-
-Different from the other project types: it adds to an **existing** device
-module rather than creating a project.
-
-```bash
-cd plesty-pm100d
-plesty init field-test          # interactive
-plesty init field-test --force  # replace an existing tests/field_test.py
-```
-
-`plesty.lib.test.field_test.FieldTestPipeline` gives every module the same gate
-sequence. The gates are the easy part — they are generic and already shared.
-What takes the time, and what three modules each got wrong at least once, is
-the **configuration**, because every line of it is a judgement about the
-instrument that no schema inspection can make:
-
-- which operations are safe to call unattended — the wrong answer moved a
-  stage, fired an exposure, and rewrote a sensor's zero calibration
-- which parameters survive being written back their own value — one crashed
-  the controlling application outright, killing every call after it
-- what is slow enough to be timed out on demand, since a call returning in two
-  milliseconds cannot be abandoned and its gate silently skips
-- which two parameters are distinguishable enough that a stale reply is
-  unambiguous
-- whether connecting is cheap, or starts an application and costs half a minute
-
-So the command asks the **device** for the *candidates*, and you for the
-*judgement*. It constructs the module hardware-free — exactly as `plesty docs`
-does, which gate d3 already requires — and reads `doc_model()`.
-
-Not the JSON schema files, and the difference is not cosmetic. A module
-registers parameters and operations in Python too (`register_config` in
-`__init__`, an `@expose_to_api` method), and none of that is in a file:
-`plesty-pm100d` alone has two such operations, which a file-reading generator
-would never offer. And for a grouped schema the keys differ —
-`get_config_list()` answers `group_prefix.param_key` while the file is keyed by
-the bare name, so an `only_keys` list built from the file would name parameters
-the pipeline cannot resolve. That is the group-name against command-prefix
-mismatch three modules hit independently.
-
-There is no fallback to the files. A device module that cannot build its doc
-model already fails gate d3, and generating from a partial picture would
-produce a file that looks complete and tests less than it claims.
-
-Each question states what the answer is used for before offering the choices,
-and each answer is followed by "why?" — the reason is written into the
-generated file as a comment, so the next reader sees why and not only what.
-
-Choices are a checkable list: arrow keys move, space selects, `a` selects all,
-`n` clears, Enter confirms, Escape backs out. Each entry shows what it is —
-a parameter's type and range, an operation's description — because choosing
-which operations may run unsupervised from a list of bare names is how the
-wrong one gets picked.
-
-Nothing is ticked to begin with, and Enter confirms whatever *is* ticked, so
-the cheapest keypress gives the most conservative answer. `a` exists but has
-to be typed. While a list is empty it says what empty means **for that
-question**, which is not the same everywhere: no operation selected means none
-is called, while no parameter selected means every one is written back.
-
-A run with no keyboard — piped input, a script, CI — falls back to typing
-comma-separated numbers rather than waiting for a keypress that never comes.
-
-**Nothing unclassified is treated as safe.** An operation you do not select is
-in neither list: it is never called, and the gate that would have called it
-skips saying so. A generated allow-list that quietly included a motion command
-would be worse than no generator at all.
-
-**What the module declares is not asked again.** An operation exposed with a
-kind — `@expose_to_api(kind="motion", position_key="MO.Position", step=1.0)`,
-`kind="lifecycle"`, `kind="control"`, or a `"kind"` block in
-`schema_func.json` (plesty-lib#39) — is shown as `[motion]`, `[lifecycle]`,
-`[control]` in the chooser, and the "acts on the world" question is asked only
-about operations that declared nothing. A `configure` operation is not offered
-at all: it is recorded as excluded, because a setting that outlives the call is
-verified by the round-trip gate. For an allow-listed motion the interview
-confirms how far the test may move it (`step`; the declared value is the
-default) and, if the module left it open, which parameter reports the position
-— a motion with neither is dropped, since the pipeline drives a motion one step
-out from that parameter and back and will not guess how far. A motion chosen as
-the slow operation is asked only how far the long move goes: the pipeline
-starts it from wherever the part is and moves it back afterwards. Both
-generated files carry the result as `OP_KINDS`.
-
-The result is two files from one interview. `tests/field_test.py` runs on the
-bench against the instrument: hardware-gated (it defines no pytest test
-functions, so CI collects nothing), wired to publish
-`reports/<instrument>/field-test.json`, and runnable against the simulator
-first:
-
-```bash
-uv run python tests/field_test.py --address mock
-uv run python tests/field_test.py --address <address>
-```
-
-`tests/field_test_client.py` runs the same checks over the wire, against the
-served module. It inherits the answers rather than asking again: an operation
-unsafe on the bench is unsafe over the network too, and a second allow-list
-would be a second chance to disagree.
-
-Neither file is replaced without `--force`: they hold answers somebody thought
-about, and a hardware run may since have corrected them.
-
-**The answers are kept.** Each one is written to `.plesty/field-test.json` as
-it is given, and every run of the command starts from what that file holds —
-so Ctrl-C loses nothing, and running `plesty init field-test` again carries on
-from where the interview stopped. A question that was displayed but not
-answered is asked again; it is marked done only once an answer is in hand. The
-file is the source of truth: edit it to change an answer without repeating the
-interview, because an answer hand-edited in the generated `.py` is overwritten
-by the next run. Answers left by an older SDK in
-`.plesty-field-test.partial.json` are moved into `.plesty/` on the first run.
-
-The run ends by saying which constant holds which answer.
-
-The interview text ships in the wheel
-(`plesty/sdk/assets/init/field-test-questions.yaml`) and the generated file's
-skeleton alongside it (`field-test.py.template`).

{plesty_sdk-0.5.0.dev1 → plesty_sdk-0.5.1}/docs/getting-started.md

@@ -27,9 +27,16 @@ plesty --project-dir ~/projects/plesty-power-meter init device \
 This generates a project pre-configured with the expected repository structure,
 `pyproject.toml`, example source files, CI pipeline (`.gitlab-ci.yml`), documentation
 stubs, and a `CHANGELOG.md`. A pre-push git hook is also installed automatically —
-it runs `plesty check` before every `git push`, using the standard declared in
-`[tool.plesty]` or, when unset, derived from the release version (`<0.1.0` pixel,
-`<1.0.0` nebula, `>=1.0.0` quantum; no tag yet = pixel).
+it runs `plesty check` before every `git push`, at the project's resolved standard
+(see [Standard resolution](commands/check.md#standard-resolution)).
+
+```{note}
+Git hooks live in `.git/` and are never cloned. Anyone who clones an existing
+project — every contributor after the one who scaffolded it — installs the hook
+once:
+
+    plesty update --install-hook
+```
 
 Use `--standard` to choose the compliance standard the generated CI pipeline enforces
 (default `pixel` — a fresh scaffold is a prototype; bump it alongside your releases), or
@@ -61,15 +68,37 @@ cd plesty-power-meter
 plesty check
 ```
 
-By default this checks against the standard declared in `[tool.plesty]` or,
-when unset, derived from the release version — a fresh scaffold without a
-release tag starts at **pixel** and ramps up to **quantum** with `v1.0.0`
-(see `plesty check`'s standard-resolution docs). Add `--standard pixel` for a fast metadata +
-code hygiene check, or `--standard nebula` for all static gates (1–6)
-without the slower quantum-only ones (7–11 and the module-type gates). Fix any reported
-issues and re-run until the check passes.
+By default this checks against the project's resolved standard — a fresh scaffold
+without a release tag starts at **pixel** and ramps up to **quantum** with `v1.0.0`
+(see [Standard resolution](commands/check.md#standard-resolution)). Add
+`--standard pixel` for a fast metadata + code hygiene check, or `--standard nebula` for
+all static gates (1–6) without the slower quantum-only ones (7–11 and the module-type
+gates). Fix any reported issues and re-run until the check passes.
+
+## 3. Test the device, without and then with hardware
+
+Under `quantum`, a device module must pass gate d1: a test that runs plesty-lib's eight
+mock gates without an instrument attached. Once the device declares its schema, generate
+that test — the command works out by itself how to reach the device without hardware:
+
+```bash
+plesty init mock-test          # writes tests/test_mock_pipeline.py
+```
+
+When the instrument is on the bench, add the field test. It interviews you about what is
+safe to run unattended, then writes a test that runs against the real device and
+publishes a report:
+
+```bash
+plesty init field-test
+uv run python tests/field_test.py --address mock        # rehearse against the simulator
+uv run python tests/field_test.py --address <address>   # then the instrument
+```
+
+See [`plesty init mock-test`](commands/init-mock-test.md) and
+[`plesty init field-test`](commands/init-field-test.md) for what each asks and writes.
 
-## 3. Preview the documentation
+## 4. Preview the documentation
 
 Start a local documentation server with live reload:
 
@@ -80,7 +109,7 @@ plesty docs serve
 Open [http://localhost:8000](http://localhost:8000) in your browser. Any changes to `.md`
 or `.rst` files in the `docs/` directory are reflected immediately.
 
-## 4. Apply license headers
+## 5. Apply license headers
 
 Keep all Python files covered by the SPDX license header:
 
@@ -91,7 +120,7 @@ plesty license update
 This reads author and maintainer information from `pyproject.toml` and writes the correct
 header to every `.py` file in the project.
 
-## 5. Update project metadata
+## 6. Update project metadata
 
 Use `plesty update` to change author info, the PyPI distribution name, or the CI pipeline
 at any time without re-scaffolding the project:
@@ -107,7 +136,7 @@ plesty update --name plesty-pm100d
 plesty update --standard quantum
 ```
 
-## 6. Deploy documentation
+## 7. Deploy documentation
 
 Documentation deployment is handled automatically by the `hub-deploy-docs` job of the
 `plesty-standard-ci` component when commits land on the default branch or a release tag is

{plesty_sdk-0.5.0.dev1 → plesty_sdk-0.5.1}/docs/index.md

@@ -26,6 +26,21 @@ plesty -d ../my-device docs serve
 Every command reads `pyproject.toml`, the `.plesty` cache, and all source paths relative to
 this directory.
 
+## The `--quiet` option
+
+The second global option, `--quiet` (`-q`), suppresses progress and guidance output —
+`plesty check`'s per-gate progress lines, the numbered **Next steps** `plesty init` ends
+with. Failures, their guidance, and the result line always print, so a quiet run still
+says what broke and whether it passed:
+
+```bash
+plesty --quiet check
+plesty -q --project-dir plesty-foo-bar init device
+```
+
+Global options go before the command name: `plesty --quiet check`, not
+`plesty check --quiet`.
+
 ## Commands at a glance
 
 | Command | Description |

{plesty_sdk-0.5.0.dev1 → plesty_sdk-0.5.1}/docs/toc.yaml

@@ -8,6 +8,11 @@ entries:
   title: check
 - file: commands/init.md
   title: init
+  entries:
+  - file: commands/init-mock-test.md
+    title: init mock-test
+  - file: commands/init-field-test.md
+    title: init field-test
 - file: commands/docs.md
   title: docs
 - file: commands/license.md