From 70189557b23de6640e83f35e0fe410c55a639800 Mon Sep 17 00:00:00 2001 From: "Marcel T." <105316958+MarcelT87@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:10:03 +0200 Subject: [PATCH 1/5] docs: add optional pinned uvx workflow --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index 40b2183..6d1ee2a 100644 --- a/README.md +++ b/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 From 7abae6e74a77a6580449c48b74b93c2b90ade4bd Mon Sep 17 00:00:00 2001 From: "Marcel T." <105316958+MarcelT87@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:10:22 +0200 Subject: [PATCH 2/5] docs: explain optional uvx installation path --- docs/INSTALL.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 9a8b139..b444e0c 100644 --- a/docs/INSTALL.md +++ b/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: From 67b2771c7b56de0148025e95db0a43a2c8a75b13 Mon Sep 17 00:00:00 2001 From: "Marcel T." <105316958+MarcelT87@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:10:36 +0200 Subject: [PATCH 3/5] docs: distinguish system identity from evidence state --- docs/SYSTEM_IDENTITY.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/SYSTEM_IDENTITY.md b/docs/SYSTEM_IDENTITY.md index 27d2269..60ceb5f 100644 --- a/docs/SYSTEM_IDENTITY.md +++ b/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 From 6c518d9b60597d3cbb210cd89be9ed91fa1a8bc6 Mon Sep 17 00:00:00 2001 From: "Marcel T." <105316958+MarcelT87@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:10:55 +0200 Subject: [PATCH 4/5] docs: record independent HW0403 cross-hardware validation --- docs/VALIDATION.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index 2fec70b..83919c7 100644 --- a/docs/VALIDATION.md +++ b/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 From 67f1ee5bf8921df57e4ef2620fe0f89462223dc8 Mon Sep 17 00:00:00 2001 From: "Marcel T." <105316958+MarcelT87@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:11:20 +0200 Subject: [PATCH 5/5] docs: add feature improvement issue form --- .github/ISSUE_TEMPLATE/improvement.yml | 55 ++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/improvement.yml diff --git a/.github/ISSUE_TEMPLATE/improvement.yml b/.github/ISSUE_TEMPLATE/improvement.yml new file mode 100644 index 0000000..e10193c --- /dev/null +++ b/.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.