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.