From 8fbb60236f3f3f0d7b56a956bc0b23cac97dde7f Mon Sep 17 00:00:00 2001
From: benma's agent <benma-agent@bitbox.swiss>
Date: Sun, 4 Oct 2026 10:28:56 +0200
Subject: [PATCH] docs: document the source of Bitcoin test vectors

The Bitcoin transaction vectors are generated in bitbox02-firmware and
must be copied byte-for-byte instead of edited in this repository.
Document their Rust source, generation instructions, and copy command.

Add AGENTS.md instructing contributors to read README.md before making
changes. Fix README typos and clarify the protobuf update instructions
and simulator test description.
---
 AGENTS.md |  3 +++
 README.md | 35 +++++++++++++++++++++++++----------
 2 files changed, 28 insertions(+), 10 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..002223a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,3 @@
+# Repository instructions
+
+Read [README.md](README.md) before making changes to this repository.
diff --git a/README.md b/README.md
index ac45f1a..bb344c5 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,13 @@
 # BitBox02 Go library
 
-The API of the api packages are currenly unstable. Expect frequent breaking changes until we start
-tagging versions.
+The API exposed by the `api` packages is currently unstable. Expect frequent breaking changes until
+we start tagging versions.
 
-## Comand to update the BitBox02 protobuf message files
-
-Clone the [BitBox02 firmware repo](https://github.com/BitBoxSwiss/bitbox02-firmware):
+## Updating the BitBox02 protobuf message files
 
 Make sure you have `protoc` and
 [protoc-gen-go](https://developers.google.com/protocol-buffers/docs/reference/go-generated)
-installed:
+installed, then clone the [BitBox02 firmware repository](https://github.com/BitBoxSwiss/bitbox02-firmware):
 
 `git clone https://github.com/BitBoxSwiss/bitbox02-firmware.git`
 
@@ -20,11 +18,28 @@ rm api/firmware/messages/backup.proto
 ./api/firmware/messages/generate.sh
 ```
 
+## Updating the Bitcoin transaction test vectors
+
+The vectors in [api/firmware/testdata/btc-transaction-test-vectors.json](api/firmware/testdata/btc-transaction-test-vectors.json)
+are generated in the BitBox02 firmware repository. Do not modify this JSON file directly.
+
+The source of truth is the Rust constructors in
+[`src/rust/bitbox-test-vectors/src/btc_transaction/cases/`](https://github.com/BitBoxSwiss/bitbox02-firmware/tree/master/src/rust/bitbox-test-vectors/src/btc_transaction/cases).
+Make changes there and regenerate the canonical JSON following the
+[test vector generation instructions](https://github.com/BitBoxSwiss/bitbox02-firmware/blob/master/src/rust/bitbox-test-vectors/README.md).
+Then copy the generated file byte-for-byte into this repository:
+
+```sh
+cp /path/to/bitbox02-firmware/src/rust/bitbox-test-vectors/testdata/btc-transaction-test-vectors.json \
+    api/firmware/testdata/btc-transaction-test-vectors.json
+```
+
 ## Simulator tests
 
-The `TestSimulator*` tests run integration against BitBox02 simulators. They are automatically
-downloaded based on [api/firmware/testdata/simulators.json](api/firmware/testdata/simulators.json),
-and each one is tested with.
+The `TestSimulator*` integration tests run against BitBox02 simulators. The simulators are
+automatically downloaded based on
+[api/firmware/testdata/simulators.json](api/firmware/testdata/simulators.json), and the tests run
+against each one.
 
 To run them, use:
 
@@ -35,5 +50,5 @@ you can run:
 
     SIMULATOR=/path/to/simulator go test -v -run TestSimulator ./...
 
-In this case, only the given simulator will be used, and the ones defined in simulators.json will be
+In this case, only the given simulator will be used, and the ones defined in `simulators.json` will be
 ignored. Make sure to use an absolute path to the simulator.