From d4a56324086b4d3b38716fa1dfa21c880c92c3bc Mon Sep 17 00:00:00 2001
From: Muhammad Hamza <hamza.00dev1@gmail.com>
Date: Mon, 10 Aug 2026 14:37:05 +0100
Subject: [PATCH] docs: add cross-platform build script commands to README

---
 README.md | 52 +++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 43 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 465e333..b74b4e4 100644
--- a/README.md
+++ b/README.md
@@ -4,37 +4,71 @@ The Python language bindings for the [bitcoindevkit](https://github.com/bitcoind
 
 See the [package on PyPI](https://pypi.org/project/bdkpython/).
 
-# Working with the submodule
+## Working with the submodule
 
 This repository uses the bdk-ffi repository as a git submodule. Here are useful tips for working with the submodule:
 
-1. When initially cloning the repo, the `bdk-ffi` submodule will be empty locally. You can intitiate/populate the directory by using the `just submodule-init` command.
+1. When initially cloning the repo, the `bdk-ffi` submodule will be empty locally. You can initiate/populate the directory by using the `just submodule-init` command.
 2. If you make local changes to the `bdk-ffi` directory while developing and want to hard delete all changes and return to the exact committed version hash of the bdk-ffi repo, use the `just submodule-reset` command.
 
 ## Local Testing and Usage
 
-1. Run one of the build script (skip the submodule update if you are making local changes to the bdk-ffi submodule)
+1. Run one of the build scripts (skip the submodule update if you are making local changes to the `bdk-ffi` submodule)
 2. Sync dependencies with `uv`
 3. Create the wheel
 4. Install the library
 5. Run the tests
 
+### 1. Build Script Commands
+
+Run the build script corresponding to your operating system:
+
+**Linux**:
+
+```sh
+bash scripts/generate-linux.sh
+```
+
+**macOS (Apple Silicon / ARM64)**:
+
 ```sh
-# If you made changes to the bdk-ffi submodule and wish to use those instead of the committed hash
-bash scripts/generate-macos-arm64.sh --skip-submodule-update
-# Otherwise
 bash scripts/generate-macos-arm64.sh
+```
+
+**macOS (Intel / x86_64)**:
+
+```sh
+bash scripts/generate-macos-x86_64.sh
+```
+
+**Windows (Git Bash / MSYS2)**:
+
+```sh
+bash scripts/generate-windows.sh
+```
+
+*Note: Pass `--skip-submodule-update` if you are making local changes to `bdk-ffi` and wish to preserve them instead of resetting to the committed submodule hash.*
 
+### 2–5. Setup, Build, Install & Test Commands
+
+```sh
+# Sync dependencies with uv
 uv sync
+
+# Create the wheel
 uv build --wheel -v
-uv pip install ./dist/bdkpython-<yourversion>.whl --force-reinstall
+
+# Install the library
+uv pip install ./dist/bdkpython-*.whl --force-reinstall
+
+# Run the tests
 uv run python -m unittest --verbose
 ```
 
 ## Build HTML API Documentation (Optional)
 
-6. Generate docs
-7. Build HTML Documentation
+1. Generate docs
+2. Build HTML Documentation
 
 ```sh
 uv run python ./docs/generate_docs.py