diff --git a/Cargo.lock b/Cargo.lock
index f27dd3f..4a69f79 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -146,7 +146,7 @@ dependencies = [
 
 [[package]]
 name = "jxr"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "jxr-core",
  "jxr-cuda",
@@ -175,7 +175,7 @@ dependencies = [
 
 [[package]]
 name = "jxr-image"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "image",
  "jxr",
@@ -188,7 +188,7 @@ version = "0.1.1"
 
 [[package]]
 name = "jxr-metal"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "j2k-core",
  "j2k-metal-support",
@@ -202,7 +202,7 @@ dependencies = [
 
 [[package]]
 name = "jxr-mpsgraph"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "j2k-metal-support",
  "j2k-mpsgraph-support",
@@ -220,7 +220,7 @@ dependencies = [
 
 [[package]]
 name = "jxr-native"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "fearless_simd",
  "jxr-core",
diff --git a/README.md b/README.md
index 532fe4c..569aa83 100644
--- a/README.md
+++ b/README.md
@@ -19,8 +19,8 @@ pixel-to-codestream encoding is not implemented.
 cargo add jxr
 ```
 
-Requires **Rust 1.99.0 or newer**. The current release is **0.3.0**; see the
-[release notes](docs/releasing.md#030-release-line) for migration details.
+Requires **Rust 1.99.0 or newer**. The current release is **0.3.1**; see the
+[release notes](docs/releasing.md#031-patch-release) for migration details.
 
 ## What it does
 
@@ -247,7 +247,7 @@ transforms. It preserves explicit alpha and output-format semantics, and rejects
 unsupported combinations instead of approximating another format.
 
 **API status.** JXR is under active development on the `0.x` release line.
-Version 0.3.0 uses exact J2K 0.12.0 dependencies; applications using the shared
+The 0.3 line uses exact J2K 0.12.0 dependencies; applications using the shared
 J2K types must update those dependencies together. Check the release notes
 before upgrading.
 
diff --git a/crates/jxr-image/Cargo.toml b/crates/jxr-image/Cargo.toml
index cdcf8bb..ec040d6 100644
--- a/crates/jxr-image/Cargo.toml
+++ b/crates/jxr-image/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "jxr-image"
 description = "Lossless ownership adapter from JPEG XR decode results to image::DynamicImage"
-version = "0.3.0"
+version = "0.3.1"
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
@@ -13,7 +13,7 @@ readme = "README.md"
 
 [dependencies]
 image.workspace = true
-jxr = { path = "../jxr", version = "=0.3.0" }
+jxr = { path = "../jxr", version = "=0.3.1" }
 thiserror.workspace = true
 
 [lints]
diff --git a/crates/jxr-metal/Cargo.toml b/crates/jxr-metal/Cargo.toml
index e15d388..bd0e9db 100644
--- a/crates/jxr-metal/Cargo.toml
+++ b/crates/jxr-metal/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "jxr-metal"
 description = "Metal execution boundary for the JXR decoder"
-version = "0.3.0"
+version = "0.3.1"
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
diff --git a/crates/jxr-mpsgraph/Cargo.toml b/crates/jxr-mpsgraph/Cargo.toml
index feb7fd3..b85e5d4 100644
--- a/crates/jxr-mpsgraph/Cargo.toml
+++ b/crates/jxr-mpsgraph/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "jxr-mpsgraph"
 description = "Direct MPSGraph tensor adapter for Metal-resident JPEG XR batches"
-version = "0.3.0"
+version = "0.4.0"
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
@@ -13,9 +13,9 @@ readme = "README.md"
 
 [dependencies]
 j2k-metal-support.workspace = true
-jxr = { path = "../jxr", version = "=0.3.0", features = ["metal"] }
+jxr = { path = "../jxr", version = "=0.3.1", features = ["metal"] }
 jxr-core = { path = "../jxr-core", version = "=0.3.0" }
-jxr-metal = { path = "../jxr-metal", version = "=0.3.0" }
+jxr-metal = { path = "../jxr-metal", version = "=0.3.1" }
 thiserror.workspace = true
 
 [target.'cfg(all(target_arch = "aarch64", target_os = "macos"))'.dependencies]
diff --git a/crates/jxr-native/Cargo.toml b/crates/jxr-native/Cargo.toml
index 0e483b2..9f8c942 100644
--- a/crates/jxr-native/Cargo.toml
+++ b/crates/jxr-native/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "jxr-native"
 description = "Safe Rust JPEG XR parser, CPU decoder, and Annex-A writer"
-version = "0.3.0"
+version = "0.3.1"
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
diff --git a/crates/jxr-test-support/Cargo.toml b/crates/jxr-test-support/Cargo.toml
index ea0394e..c1d328b 100644
--- a/crates/jxr-test-support/Cargo.toml
+++ b/crates/jxr-test-support/Cargo.toml
@@ -14,8 +14,8 @@ metal = ["jxr/metal"]
 cuda = ["jxr/cuda"]
 
 [dependencies]
-jxr = { path = "../jxr", version = "=0.3.0" }
-jxr-native = { path = "../jxr-native", version = "=0.3.0" }
+jxr = { path = "../jxr", version = "=0.3.1" }
+jxr-native = { path = "../jxr-native", version = "=0.3.1" }
 rayon.workspace = true
 thiserror.workspace = true
 
diff --git a/crates/jxr/Cargo.toml b/crates/jxr/Cargo.toml
index 3e24dfc..02425ac 100644
--- a/crates/jxr/Cargo.toml
+++ b/crates/jxr/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "jxr"
 description = "JPEG XR decoder and Annex-A writer with optional Metal and CUDA reconstruction"
-version = "0.3.0"
+version = "0.3.1"
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
@@ -19,8 +19,8 @@ cuda = ["dep:jxr-cuda"]
 
 [dependencies]
 jxr-core = { path = "../jxr-core", version = "=0.3.0" }
-jxr-native = { path = "../jxr-native", version = "=0.3.0" }
-jxr-metal = { path = "../jxr-metal", version = "=0.3.0", optional = true }
+jxr-native = { path = "../jxr-native", version = "=0.3.1" }
+jxr-metal = { path = "../jxr-metal", version = "=0.3.1", optional = true }
 jxr-cuda = { path = "../jxr-cuda", version = "=0.3.0", optional = true }
 rayon.workspace = true
 thiserror.workspace = true
diff --git a/crates/jxr/fuzz/Cargo.lock b/crates/jxr/fuzz/Cargo.lock
index f1ee6b9..e1ccbc5 100644
--- a/crates/jxr/fuzz/Cargo.lock
+++ b/crates/jxr/fuzz/Cargo.lock
@@ -110,7 +110,7 @@ dependencies = [
 
 [[package]]
 name = "jxr"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "jxr-core",
  "jxr-cuda",
@@ -151,7 +151,7 @@ version = "0.1.1"
 
 [[package]]
 name = "jxr-native"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "fearless_simd",
  "jxr-core",
diff --git a/docs/releasing.md b/docs/releasing.md
index 313e511..5470d10 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -130,3 +130,41 @@ passed for the tagged source. CPU, Annex-A writer, Metal, and CUDA reference
 comparisons each passed 517 in-scope cases, with 179 declared scope exclusions
 and no failures. The reports and hardware benchmark results are attached to
 the [0.3.0 release](https://github.com/frames-sg/jxr/releases/tag/v0.3.0).
+
+## 0.3.1 patch release
+
+This patch release makes decoding faster without changing decoded output or
+the existing decode contracts. CPU entropy decoding caches packet bits, decodes
+run prefixes and per-symbol codes inline, and places coefficients directly in
+their adaptive scan. Spatial tiles decode straight into the coefficient arena
+or caller-owned Metal staging instead of being copied after the tile decode.
+CPU inverse transforms, overlap filters, and common integer output packing use
+four-lane and row-parallel paths with checked scalar fallbacks.
+
+Metal specializes output stores, batches overlap dispatches, reuses
+coefficient staging across submissions, and overlaps `MetalBatchDecoder`
+preparation with GPU reconstruction. Automatic Metal routing now promotes at
+2^21 reconstructed coefficients instead of 16,384, so `Auto` decodes smaller
+images on the CPU; explicit Metal requests are unchanged. MPSGraph batch
+preparation runs on the decoder's worker pool and decodes entropy directly into
+Metal staging, so prepared groups run without a coefficient upload. A staging
+allocation failure now fails `prepare` rather than a later run.
+
+Additions are `MetalDecoderSession::stage_diagnostics` with
+`MetalStageDiagnostics`, the `staging` field of the non-exhaustive
+`MetalBufferPoolsDiagnostics`, and `CpuBatchDecoder::install`. Per-change
+measurements are in pull requests #12 through #19.
+
+Publish the changed packages and their exact-version dependents in this order:
+
+1. `jxr-native` 0.3.1
+2. `jxr-metal` 0.3.1
+3. `jxr` 0.3.1
+4. `jxr-image` 0.3.1
+5. `jxr-mpsgraph` 0.4.0
+
+`jxr-math` 0.1.1, `jxr-core` 0.3.0, and `jxr-cuda` 0.3.0 are unchanged and stay
+at their published versions. `jxr-image` changes only its exact `jxr` pin.
+`jxr-mpsgraph` moves to 0.4.0 because `MpsGraphPreparedGroup` and
+`MpsGraphPreparedBatch` now hold staged Metal plans and are no longer
+`UnwindSafe` or `RefUnwindSafe`; its other public API is unchanged.