diff --git a/crates/ruvector-dither/README.md b/crates/ruvector-dither/README.md
new file mode 100644
index 00000000..a0780742
--- /dev/null
+++ b/crates/ruvector-dither/README.md
@@ -0,0 +1,75 @@
+# ruvector-dither
+
+Deterministic, low-discrepancy **pre-quantization dithering** for low-bit
+neural network inference on tiny devices (WASM, Seed, STM32).
+
+## Why dither?
+
+Quantizers at 3/5/7 bits can align with power-of-two boundaries, producing
+idle tones, sticky activations, and periodic errors that degrade accuracy.
+A sub-LSB pre-quantization offset:
+
+- Decorrelates the signal from grid boundaries.
+- Pushes quantization error toward high frequencies (blue-noise-like),
+  which average out downstream.
+- Uses **no RNG** -- outputs are deterministic, reproducible across
+  platforms (WASM / x86 / ARM), and cache-friendly.
+
+## Features
+
+- **Golden-ratio sequence** -- best 1-D equidistribution, irrational period (never repeats).
+- **Pi-digit table** -- 256-byte cyclic lookup, exact reproducibility from a tensor/layer ID.
+- **Per-channel dither pools** -- structurally decorrelated channels without any randomness.
+- **Scalar, slice, and integer-code quantization** helpers included.
+- **`no_std`-compatible** -- zero runtime dependencies; enable with `features = ["no_std"]`.
+
+## Quick start
+
+```rust
+use ruvector_dither::{GoldenRatioDither, PiDither, quantize_dithered};
+
+// Golden-ratio dither, 8-bit, epsilon = 0.5 LSB
+let mut gr = GoldenRatioDither::new(0.0);
+let q = quantize_dithered(0.314, 8, 0.5, &mut gr);
+assert!(q >= -1.0 && q <= 1.0);
+
+// Pi-digit dither, 5-bit
+let mut pi = PiDither::new(0);
+let q2 = quantize_dithered(0.271, 5, 0.5, &mut pi);
+assert!(q2 >= -1.0 && q2 <= 1.0);
+```
+
+### Per-channel batch quantization
+
+```rust
+use ruvector_dither::ChannelDither;
+
+let mut cd = ChannelDither::new(/*layer_id=*/ 0, /*channels=*/ 8, /*bits=*/ 5, /*eps=*/ 0.5);
+let mut activations = vec![0.5_f32; 64]; // shape [batch=8, channels=8]
+cd.quantize_batch(&mut activations);
+```
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `golden` | `GoldenRatioDither` -- additive golden-ratio quasi-random sequence |
+| `pi` | `PiDither` -- cyclic 256-byte table derived from digits of pi |
+| `quantize` | `quantize_dithered`, `quantize_slice_dithered`, `quantize_to_code` |
+| `channel` | `ChannelDither` -- per-channel dither pool seeded from layer/channel IDs |
+
+## Trait: `DitherSource`
+
+Implement `DitherSource` to plug in your own deterministic sequence:
+
+```rust
+pub trait DitherSource {
+    /// Return the next zero-mean offset in [-0.5, +0.5].
+    fn next_unit(&mut self) -> f32;
+}
+```
+
+## License
+
+Licensed under either of [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+or [MIT License](http://opensource.org/licenses/MIT) at your option.
diff --git a/crates/thermorust/README.md b/crates/thermorust/README.md
new file mode 100644
index 00000000..b2ff3401
--- /dev/null
+++ b/crates/thermorust/README.md
@@ -0,0 +1,71 @@
+# thermorust
+
+A minimal thermodynamic neural-motif engine for Rust. Treats computation as
+**energy-driven state transitions** with Landauer-style dissipation tracking
+and Langevin/Metropolis noise baked in.
+
+## Features
+
+- **Ising and soft-spin Hamiltonians** with configurable coupling matrices and local fields.
+- **Metropolis-Hastings** (discrete) and **overdamped Langevin** (continuous) dynamics.
+- **Landauer dissipation accounting** -- every accepted irreversible transition charges
+  kT ln 2 of heat, giving a physical energy audit of your computation.
+- **Langevin and Poisson spike noise** sources satisfying the fluctuation-dissipation theorem.
+- **Thermodynamic observables** -- magnetisation, pattern overlap, binary entropy,
+  free energy, and running energy/dissipation traces.
+- **Pre-wired motif factories** -- ring, fully-connected, Hopfield memory, and
+  random soft-spin networks ready to simulate out of the box.
+- **Simulated annealing** helpers for both discrete and continuous models.
+
+## Quick start
+
+```rust
+use thermorust::{motifs::IsingMotif, dynamics::{Params, anneal_discrete}};
+use rand::SeedableRng;
+
+let mut motif = IsingMotif::ring(16, 0.2);
+let params    = Params::default_n(16);
+let mut rng   = rand::rngs::StdRng::seed_from_u64(42);
+
+let trace = anneal_discrete(
+    &motif.model, &mut motif.state, &params, 10_000, 100, &mut rng,
+);
+println!("Mean energy: {:.3}", trace.mean_energy());
+println!("Heat shed:   {:.3e} J", trace.total_dissipation());
+```
+
+### Continuous soft-spin simulation
+
+```rust
+use thermorust::{motifs::SoftSpinMotif, dynamics::{Params, anneal_continuous}};
+use rand::SeedableRng;
+
+let mut motif = SoftSpinMotif::random(32, 1.0, 0.5, 42);
+let params    = Params::default_n(32);
+let mut rng   = rand::rngs::StdRng::seed_from_u64(7);
+
+let trace = anneal_continuous(
+    &motif.model, &mut motif.state, &params, 5_000, 50, &mut rng,
+);
+```
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `state` | `State` -- activation vector with cumulative dissipation counter |
+| `energy` | `EnergyModel` trait, `Ising`, `SoftSpin`, `Couplings` |
+| `dynamics` | `step_discrete` (MH), `step_continuous` (Langevin), annealers |
+| `noise` | Langevin Gaussian and Poisson spike noise sources |
+| `metrics` | Magnetisation, overlap, entropy, free energy, `Trace` |
+| `motifs` | Pre-wired ring, fully-connected, Hopfield, and soft-spin motifs |
+
+## Dependencies
+
+- `rand` 0.8 (with `small_rng`)
+- `rand_distr` 0.4
+
+## License
+
+Licensed under either of [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+or [MIT License](http://opensource.org/licenses/MIT) at your option.