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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report an incorrect result, crash, or unexpected runtime behavior
+title: "[Bug]: "
+labels: bug
+---
+
+## What happened?
+
+Describe the observed behavior.
+
+## Reproduction
+
+Provide the smallest command or code sample that reproduces the issue.
+
+## Environment
+
+- OS and hardware:
+- Rust version (`rustc --version`):
+- Backend (`cpu` or `metal`):
+- Does the issue reproduce with the CPU backend?
+
+## Expected behavior
+
+Describe the expected result.
+
+## Relevant logs
+
+Include the smallest relevant error output, backtrace, or parity diff.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Propose an improvement to batch_forge
+title: "[Feature]: "
+labels: enhancement
+---
+
+## Problem
+
+What limitation or workflow does this improve?
+
+## Proposed change
+
+Describe the behavior or API you would like.
+
+## Alternatives considered
+
+Describe any workarounds or alternative approaches.
+
+## Success criteria
+
+What outcome would make this feature complete?
+
+## Compatibility or performance impact
+
+Note any expected platform, API, memory, or throughput tradeoffs.

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Summary
+
+Describe the change and why it is needed.
+
+## Risks
+
+Note any compatibility, performance, or behavior risks.
+
+## Documentation
+
+- [ ] Public API docs and user-facing guides updated when applicable
+
+## Tests
+
+- [ ] Relevant tests added or updated when behavior changes
+
+## Validation
+
+- [ ] `cargo fmt --check`
+- [ ] `cargo check`
+- [ ] `cargo clippy --all-targets`
+- [ ] `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,56 @@
+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: asset downloader tests (no network)
+        run: python3 -m unittest discover -s python -p 'test_*.py'
+      - name: rustfmt
+        run: cargo fmt --all -- --check
+      - name: clippy
+        run: cargo clippy --all-targets
+      - name: test (CPU and CLI)
+        run: cargo test --lib --bins
+      - name: CLI smoke tests without model assets
+        run: |
+          cargo run --quiet --bin generate -- --help
+          cargo run --quiet --bin generate -- --version
+          if cargo run --quiet --bin generate -- --temperature NaN; then exit 1; fi
+          if cargo run --quiet --bin batch_forge -- --model /missing/checkpoint.safetensors; then exit 1; fi
+
+  # 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 --bins

.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,18 @@
+# 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 check
+cargo clippy --all-targets
+cargo test --lib
+```
+
+If the formatting check reports changes, run `cargo fmt`, review the diff, then run the check again.
+
+The formatting, compile, lint, 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.
+
+## Reporting issues
+
+Use the issue templates when reporting a bug or proposing an enhancement; their `bug` and `enhancement` labels help keep reports organized. For runtime bugs, include the backend, hardware, and smallest reproduction command.