Docs: add uv workflow and cross-hardware validation

.github/ISSUE_TEMPLATE/improvement.yml

@@ -0,0 +1,55 @@
+name: Feature / improvement
+description: Suggest a documentation, workflow, UX or tool improvement
+title: "Improvement: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for improvements that are not bug reports or Evidence submissions.
+
+        Please do not paste credentials, full raw logs, private host configuration, or other
+        sensitive data. Security vulnerabilities should follow SECURITY.md instead.
+
+  - type: textarea
+    id: improvement
+    attributes:
+      label: What would you improve?
+      description: Describe the proposed change and the problem or friction it would solve.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Suggested approach
+      description: Optional. Include example commands or wording if useful.
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: ebus-evidence version
+      description: Optional. Include the version if the suggestion relates to current tool behavior.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Documentation
+        - Installation / setup
+        - CLI / workflow
+        - Evidence profile / research workflow
+        - Contribution / GitHub UX
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional non-sensitive details
+      description: Optional context that helps evaluate the improvement.

README.md

@@ -66,6 +66,29 @@ The installer creates a local `.venv`, installs the checkout and enables the
 local `./evidence` launcher. Runtime data such as `data/evidence-state.json`
 and `data/evidence.zip` are kept relative to that checkout. It does not
 configure or access the eBUS adapter.
+For users who already use [uv](https://docs.astral.sh/uv/), an optional
+checkout-free path is also supported. Pin a release or exact commit and run all
+commands from the same working directory because the normal `data/` files are
+relative to that directory:
+
+```bash
+mkdir ebus-evidence-run
+cd ebus-evidence-run
+
+uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
+  ebus-evidence doctor --raw /path/to/ebusd.raw --profile hw5103-open-evidence
+
+uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
+  ebus-evidence import --raw /path/to/ebusd.raw --profile hw5103-open-evidence
+
+uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
+  ebus-evidence export
+```
+
+This is an optional convenience path, not a replacement for the beginner
+installer. A VCS-installed `uvx` run may report `Source commit: unavailable`
+because the installed package need not retain a Git checkout; runtime and
+profile SHA-256 provenance are still recorded and verified.
 
 ### 2. Check
 

docs/INSTALL.md

@@ -171,6 +171,39 @@ If `.venv` is instead an unexpected ordinary directory or a symbolic link,
 the installer stops and asks you to move/remove it manually rather than
 deleting unknown files.
 
+### Optional: run with uvx
+
+If you already use [uv](https://docs.astral.sh/uv/), you can run the packaged
+CLI without creating a repository checkout. Keep all commands in the same
+working directory so the default `data/` state, contexts and bundle remain
+together.
+
+For reproducible Evidence, pin an immutable release or exact commit instead of
+implicitly following the current branch head:
+
+```bash
+mkdir ebus-evidence-run
+cd ebus-evidence-run
+
+uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
+  ebus-evidence doctor --raw /path/to/ebusd.raw --profile hw5103-open-evidence
+
+uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
+  ebus-evidence import --raw /path/to/ebusd.raw --profile hw5103-open-evidence
+
+uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
+  ebus-evidence export
+```
+
+The generated bundle still records and verifies tool-runtime and profile
+SHA-256 provenance. A VCS-installed `uvx` package may show
+`Source commit: unavailable` because the installed environment does not
+necessarily retain Git metadata. This does not by itself make the bundle
+invalid; use the pinned command together with the recorded hashes for
+reproducibility.
+
+`uv` is an additional tool dependency, so the normal clone + `install.sh`
+workflow remains the recommended beginner path.
 ### Advanced/manual installation
 
 The standard Python path remains supported:

docs/SYSTEM_IDENTITY.md

@@ -9,6 +9,15 @@ Evidence is most useful when it can be tied to a clearly described hardware and
 
 The product name is not used to guess the bus hardware.
 
+This file is **not** the Evidence state:
+
+- `data/evidence-state.json` contains the collected observation/check state;
+- `data/system.json` contains only the optional privacy-minimized
+  hardware/firmware identity described on this page.
+
+Both may be included in the same exported Evidence bundle, but they serve
+different purposes.
+
 ---
 
 ## Safety boundary

docs/VALIDATION.md

@@ -137,6 +137,47 @@ The final independent Evidence checks included:
   `0aff020000000000030001`;
 - export: `VALID`, `clean`, public submission `PASS`.
 
+## Cross-hardware real-world check
+
+Issue #38 added an independent Vaillant flexoTHERM exclusive installation with
+a different hardware generation:
+
+```text
+08  HMU00  SW0308 / HW0403
+15  VRC 700 (70000)  SW0614 / HW6903
+76  VWZ00  SW0308 / HW0403
+```
+
+A static import over about 6 h 50 min produced:
+
+```text
+Frames observed ...... 15,987
+Passive frames ....... 14,122
+ebusd initiated ....... 1,865
+Non-frames ........... 4,366
+Skipped .............. 0
+```
+
+The normal `hw5103-open-evidence` v2 profile produced zero matches for its
+four current HW5103 research discriminators. That is useful negative
+cross-hardware evidence and supports keeping the bundled v2 profile scoped to
+its current HW5103 research path.
+
+A separate, unmerged experimental profile was then run against the identical
+source window. It reproduced three structural families on the older hardware:
+
+```text
+B507 /0209XX ........ 387
+B505 /025c00 ........ 396
+B510 /020601 ........ 79
+```
+
+while B508 `/0209` and the tested B531/B510 LPC path had zero matches in that
+window. These results are research discriminators, not new public protocol
+semantics, and the experimental profile is not part of the rc2 release.
+
+The returned experimental bundle verified as `VALID`, deterministic and
+public-submission `PASS`, with the privacy-minimized system identity included.
 ## Bundle/verifier robustness
 
 Separate from transport parsing, bundle verification is hardened against