add mdbook contributing documentation

* also address review comments for Makefile,
  docs/install-and-build-mdbook.sh script

Author: Priyankasaggu11929

Makefile

@@ -324,5 +324,5 @@ docs: ## Build the mdBook locally using the same script Netlify uses.
 	GO_VERSION=$(GO_VERSION) MDBOOK_VERSION=$(MDBOOK_VERSION) $(MDBOOK_SCRIPT)
 
 .PHONY: docs-serve
-docs-serve: ## Serve mdBook locally (requires mdbook installed locally).
+docs-serve: ## Serve mdBook locally.
 	GO_VERSION=$(GO_VERSION) MDBOOK_VERSION=$(MDBOOK_VERSION) $(MDBOOK_SCRIPT) serve docs/book --open

docs/README.md

@@ -0,0 +1,70 @@
+## Documentation (mdBook)
+
+This repository’s documentation is built using [**mdBook**](https://github.com/rust-lang-nursery/mdBook).
+
+Local builds and hosted builds use the same build script [1] to ensure consistent behavior.
+
+## Local documentation workflows
+
+All documentation targets **must be run from the repository root**.
+
+### Available Makefile targets
+
+```bash
+make docs        # Build the mdBook locally using the shared build script
+make docs-serve  # Serve the mdBook locally
+```
+
+## Build script contract
+
+The documentation build is driven by:
+
+```
+docs/book/install-and-build-mdbook.sh
+```
+
+This script defines how mdBook is installed and executed.
+
+### Environment variables
+
+The build relies on the following environment variables:
+
+| Variable         | Description                      |
+| ---------------- | -------------------------------- |
+| `GO_VERSION`     | Go version used during the build |
+| `MDBOOK_VERSION` | mdBook version to install/use    |
+
+
+## Version synchronization requirements
+
+The environment variables used for documentation builds must be kept **consistent across the repository**.
+
+When either `GO_VERSION` or `MDBOOK_VERSION` is changed, the update **must be applied in all of the following locations**:
+
+1. **Makefile**
+   Used for local documentation builds and serving.
+
+2. **`netlify.toml`**
+   Used for hosted and preview builds.
+
+3. **`docs/book/install-and-build-mdbook.sh`**
+   Used as the canonical build script.
+
+## Editing documentation
+
+1. Make changes under:
+
+   ```
+   docs/book/src/
+   ```
+2. Preview changes locally:
+
+   ```bash
+   make docs-serve
+   ```
+3. Commit only source files; generated output is produced during the build.
+
+---
+
+[1] [`docs/book/install-and-build-mdbook.sh`](book/install-and-build-mdbook.sh)
+

docs/book/install-and-build-mdbook.sh

@@ -37,14 +37,10 @@ os=$(go env GOOS)
 arch=$(go env GOARCH)
 
 # translate arch to rust's conventions (if we can)
-if [[ ${arch} == "amd64" ]]; then
+if [[ ${arch} == "amd64" || ${arch} == "x86" ]]; then
     arch="x86_64"
-elif [[ ${arch} == "x86" ]]; then
-    arch="i686"
 elif [[ ${arch} == "arm64" ]]; then
-    # arm64 is not supported for v0.4.40 mdbook, so using x86_64 type.
-    # Once the mdbook is upgraded to latest, use 'aarch64'
-    arch="x86_64"
+    arch="aarch64"
 fi
 
 # translate os to rust's conventions (if we can)