From 3500629c0305a36fcdc4b9ee0973cf2a9250e52f Mon Sep 17 00:00:00 2001
From: Asjad <m.asjad2401@gmail.com>
Date: Sat, 1 Aug 2026 12:12:44 +0500
Subject: [PATCH] docs: update README, add CHANGELOG

---
 CHANGELOG.md | 22 ++++++++++++++++++++++
 README.md    | 30 +++++++++++++++++++++++++-----
 2 files changed, 47 insertions(+), 5 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..0aead5f
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- ONNX interpreter support for Conv2d, fused BatchNormalization, MaxPool2d,
+  AveragePool2d, and GlobalAveragePool.
+- GitHub Actions CI: `cargo build`, `cargo fmt` / `cargo clippy` (non-blocking),
+  and Python tests via `maturin develop`.
+- Branch protection on `main`: pull requests required, `cargo build` and
+  `python tests (maturin)` checks required to merge.
+- ONNX interpreter with Gemm, Linear, Relu, Sigmoid, Tanh, Gelu, Softmax,
+  LogSoftmax, Add, Sub, Mul, Div, Reshape, Flatten, and Transpose ops.
+- Zero-copy numpy ↔ Burn tensor bridge (`roundtrip`).
+- Initial maturin/pyo3 project scaffold, `burn-flex` + `onnx-ir` dependencies.
+
+[Unreleased]: https://github.com/asjad2401/burn-python/commits/main
diff --git a/README.md b/README.md
index 8b2e6a0..6be935a 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,46 @@
 # burn-python
 
+[![CI](https://github.com/asjad2401/burn-python/actions/workflows/ci.yml/badge.svg)](https://github.com/asjad2401/burn-python/actions/workflows/ci.yml)
+
 Python inference frontend for the [Burn](https://github.com/tracel-ai/burn) deep learning framework.
 
-Load any ONNX model and run inference from Python — numpy in, numpy out. No Rust required.
+Load an ONNX model and run inference from Python — numpy in, numpy out. No Rust required.
 
 ```python
 import burn_python as burn
 import numpy as np
 
-model = burn.load_onnx("resnet50.onnx")
-output = model(np.random.randn(1, 3, 224, 224).astype(np.float32))
+model = burn.load_onnx("model.onnx")
+x = np.random.randn(1, 3, 224, 224).astype(np.float32)
+output = model([x])[0]
 ```
 
 ## Status
 
-Early development. Stage 1 (numpy ↔ Burn tensor bridge) in progress.
+Early development. The numpy ↔ Burn tensor bridge is done, and the ONNX interpreter
+currently supports:
+
+- **Linear algebra**: Gemm, Linear
+- **Activations**: Relu, Sigmoid, Tanh, Gelu, Softmax, LogSoftmax
+- **Elementwise**: Add, Sub, Mul, Div
+- **Shape ops**: Reshape, Flatten, Transpose
+- **Conv/pooling**: Conv2d, BatchNormalization (fused), MaxPool2d, AveragePool2d, GlobalAveragePool
+
+Enough to run simple MLPs and small CNNs; more ops are being added incrementally.
 
 ## Building
 
 ```bash
 pip install maturin
-maturin develop
+maturin develop --release
+```
+
+## Testing
+
+```bash
+python tests/make_test_model.py   # generates tests/mlp.onnx
+python tests/test_bridge.py       # numpy <-> Burn tensor bridge
+python tests/compare_ort.py       # correctness + perf vs ONNX Runtime
 ```
 
 ## License