docs: add benchmarks, correctness, and update README; feat: add error…

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+Describe the change and why it is needed.
+
+## Validation
+
+- [ ] `cargo fmt --check`
+- [ ] `cargo test --lib`
+- [ ] Metal parity check run when applicable (`cargo test --test parity -- --nocapture`)
+- [ ] End-to-end GPT-2 check run when applicable (`cargo test --test gpt2_e2e -- --nocapture`)

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
+
+jobs:
+  # Portable path: the CPU reference, loader, model, and async engine build and
+  # test on Linux (the Metal backend is cfg'd out on non-macOS targets).
+  lint-and-test:
+    name: fmt + clippy + test (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: rustfmt
+        run: cargo fmt --all -- --check
+      - name: clippy
+        run: cargo clippy --all-targets
+      - name: test (CPU)
+        run: cargo test --lib
+
+  # Apple Silicon: full build incl. Metal kernels + CPU unit tests. The on-device
+  # CPU↔Metal parity suite (`cargo test --test parity`) needs a Metal device and
+  # is run locally; see docs/correctness.md.
+  macos-build:
+    name: build + test (macos)
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: clippy (incl. Metal backend)
+        run: cargo clippy --all-targets
+      - name: build
+        run: cargo build --release --all-targets
+      - name: test (CPU unit tests)
+        run: cargo test --lib

.gitignore

@@ -1,17 +1,17 @@
 # Rust
 /target
-Cargo.lock
 
 # Python
 venv/
 __pycache__/
 *.pyc
 
-# ML Weights & Data
+# ML Weights & Data (don't commit large binaries; generate them locally)
 *.safetensors
 *.bin
 *.pt
 *.ckpt
 
 # MacOS
 .DS_Store
+models/

CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+Small, focused changes are easiest to review. Before opening a pull request, run the checks that match the code you changed:
+
+```bash
+cargo fmt --check
+cargo test --lib
+```
+
+If the formatting check reports changes, run `cargo fmt`, review the diff, then run the check again.
+
+The formatting and library-test preflight is CPU-only and needs no model assets. Metal parity checks require Apple Silicon macOS, and the end-to-end GPT-2 check requires the downloaded model assets. See the [test command reference](docs/test-matrix.md) for the complete matrix and [troubleshooting guide](docs/troubleshooting.md) for setup notes.