🔧 docs: real-world examples from prism-core

- pipeline.md: PureBeam constructors, smap usage, propagate function
- context.md: why Beam uses direct matches instead of Eh
- flight-recorder.md: ScalarLoss on eigenvalue decomposition, Transport holonomy
- migration.md: case study — ShannonLoss to ScalarLoss, constructor methods
- README.md: "See it in action" section linking to prism-core

Author: Mara

README.md

@@ -129,6 +129,10 @@ Block macro for implicit loss accumulation — `eh! { }` will do what `Eh` does
 - [Flight recorder](docs/flight-recorder.md) — `Failure(E, L)` as production telemetry, not stack traces
 - [Benchmarks](docs/benchmarks.md) — 0.65 ns per honest step, zero on the success path
 
+## See it in action
+
+- **[prism-core](https://github.com/systemic-engineering/prism/tree/main/core)** — spectral optics pipeline. Uses `Imperfect` as the value carrier inside `Beam`, with a custom `ScalarLoss` type for eigenvalue decomposition. 182 tests.
+
 ## License
 
 Apache-2.0

docs/context.md

@@ -209,4 +209,30 @@ assert_eq!(result.ok(), Some(10));
 assert_eq!(result.loss().steps(), 2);  // the cost of getting here survives
 ```
 
+## Why prism-core doesn't use Eh
+
+prism-core's `Beam` trait IS its own composition context. The `tick` primitive destructures the beam's `Imperfect` to extract inner values for building new beam structs — a pattern that requires direct match arms rather than `Eh`'s `Result`-based extraction.
+
+From [`core/src/beam.rs`](https://github.com/systemic-engineering/prism/blob/main/core/src/beam.rs):
+
+```rust
+fn tick<T, NE>(self, next: Imperfect<T, NE, L>) -> PureBeam<Out, T, NE, L> {
+    match self.imperfect {
+        Imperfect::Failure(_, _) => panic!("tick on Err beam — check is_ok() first"),
+        Imperfect::Success(old_out) => PureBeam {
+            input: old_out,
+            imperfect: next,
+        },
+        Imperfect::Partial(old_out, loss) => PureBeam {
+            input: old_out,
+            imperfect: propagate(loss, next),
+        },
+    }
+}
+```
+
+The beam needs `old_out` to construct the new struct's `input` field. `Eh.eh()` would discard that inner value into a `Result<T, E>`, losing the structural information beam needs.
+
+This is the right pattern: `Eh` is for code that consumes `Imperfect` values and produces a final result. `Beam` is for code that builds new `Imperfect` values from old ones while carrying structural context. Different layers, different tools.
+
 [Back to README](../README.md) · [Terni-functor →](terni-functor.md)

docs/flight-recorder.md

@@ -127,4 +127,44 @@ represent them. The type doesn't have a place to put the information.
 
 Those empty cells are why this crate exists.
 
+## Real-world: prism-core's ScalarLoss
+
+prism-core implements its own `Loss` type — [`ScalarLoss`](https://github.com/systemic-engineering/prism/blob/main/core/src/scalar_loss.rs) — for eigenvalue decomposition. When a spectral projection zeroes out eigenvalues below a precision threshold, the magnitude of what was discarded IS the loss. This is the flight recorder in practice: the loss tells you how much signal was thrown away at each stage of a spectral pipeline.
+
+From `core/src/scalar_loss.rs`:
+
+```rust
+/// A scalar information loss measured in bits.
+#[derive(Clone, Debug, PartialEq, Default)]
+pub struct ScalarLoss(pub f64);
+
+impl Loss for ScalarLoss {
+    fn zero() -> Self { ScalarLoss(0.0) }
+    fn total() -> Self { ScalarLoss(f64::INFINITY) }
+    fn is_zero(&self) -> bool { self.0 == 0.0 }
+    fn combine(self, other: Self) -> Self { ScalarLoss(self.0 + other.0) }
+}
+```
+
+The `combine` is addition — scalar losses accumulate linearly. `total()` is infinity, acting as a proper absorbing element.
+
+In the `Transport` trait (the bundle tower's parallel transport operation), the holonomy IS the loss — comprehension always costs something:
+
+```rust
+impl Transport for TestBundle {
+    type Holonomy = ScalarLoss;
+    fn transport(&self, state: &[f64; 4]) -> Imperfect<[f64; 4], Infallible, ScalarLoss> {
+        let compressed = [state[0], state[1], 0.0, 0.0];
+        let loss = state[2].abs() + state[3].abs();
+        if loss == 0.0 {
+            Imperfect::success(compressed)
+        } else {
+            Imperfect::partial(compressed, ScalarLoss::new(loss))
+        }
+    }
+}
+```
+
+The two zeroed-out dimensions are measured. The flight recorder captures exactly what was discarded, in bits. Downstream consumers see `Partial` and know: a value exists, but it cost something. The loss says how much.
+
 [Back to README](../README.md) · [Loss types →](loss-types.md) · [Benchmarks →](benchmarks.md)

docs/migration.md

@@ -166,4 +166,40 @@ assert_eq!(error, "gone");
 assert_eq!(loss.steps(), 7);
 ```
 
+## Case study: prism-core
+
+prism-core migrated from `ShannonLoss` (a former terni type) to a local `ScalarLoss` when terni removed `ShannonLoss` upstream. The migration also replaced manual enum variant constructors with terni's constructor methods.
+
+**Before:**
+
+```rust
+// ShannonLoss from terni (removed upstream)
+use terni::ShannonLoss;
+
+Imperfect::Success(output)
+Imperfect::Partial(output, ShannonLoss::new(bits))
+Imperfect::Failure(error, ShannonLoss::new(0.0))
+```
+
+**After:**
+
+```rust
+// ScalarLoss — core's own Loss impl
+use prism_core::ScalarLoss;
+
+Imperfect::success(output)
+Imperfect::partial(output, ScalarLoss::new(bits))
+Imperfect::failure(error)  // zero loss by default
+```
+
+Key decisions in the migration:
+
+1. **Own the loss type.** When the upstream type changed, core defined `ScalarLoss` locally — a 39-line file implementing the `Loss` monoid with additive `combine`. No external dependency for a domain-specific measurement.
+
+2. **Constructor methods over enum variants.** `Imperfect::failure(e)` replaces `Imperfect::Failure(e, L::zero())` — the zero loss is the common case and shouldn't require spelling out. `Imperfect::failure_with_loss(e, l)` for the rare case where accumulated loss needs explicit attachment.
+
+3. **Gradual.** The `Beam` trait's `tick` primitive still pattern-matches on `Imperfect` variants directly — because it needs to destructure the inner values to build new beam structs. The refactor targeted constructors and leaf code, not the pipeline primitive.
+
+Total diff: 6 files changed, 27 insertions, 27 deletions. All 182 tests pass unchanged.
+
 [Back to README](../README.md) · [Loss types →](loss-types.md)

docs/pipeline.md

@@ -171,4 +171,57 @@ assert_eq!(a, b);
 assert_eq!(b, c);
 ```
 
+## Real-world: prism-core
+
+prism-core's `Beam` trait uses `Imperfect` as its value carrier. Every beam carries an `Imperfect<Out, E, L>` internally, and the semifunctor `smap` maps over it using `.eh()`-style closures that return `Imperfect`.
+
+From [`core/src/beam.rs`](https://github.com/systemic-engineering/prism/blob/main/core/src/beam.rs) — the `smap` method on the `Beam` trait:
+
+```rust
+fn smap<T>(
+    self,
+    f: impl FnOnce(&Self::Out) -> Imperfect<T, Self::Error, Self::Loss>,
+) -> Self::Tick<T, Self::Error> {
+    let imp = match self.result() {
+        Imperfect::Success(v) | Imperfect::Partial(v, _) => f(v),
+        Imperfect::Failure(_, _) => panic!("smap on Err beam"),
+    };
+    self.tick(imp)
+}
+```
+
+And how it's used in practice — Traversal's split operation collapses a multi-element result:
+
+```rust
+let focused = traversal.focus(seed(vec![1, 2, 3]));
+let first = focused.smap(|v| Imperfect::success(v.first().cloned().unwrap_or(0)));
+assert_eq!(first.result().ok(), Some(&2));
+```
+
+The `PureBeam` constructors use terni's constructor methods directly:
+
+```rust
+pub fn ok(input: In, output: Out) -> Self {
+    Self { input, imperfect: Imperfect::success(output) }
+}
+pub fn partial(input: In, output: Out, loss: L) -> Self {
+    Self { input, imperfect: Imperfect::partial(output, loss) }
+}
+pub fn err(input: In, error: E) -> Self {
+    Self { input, imperfect: Imperfect::failure(error) }
+}
+```
+
+Loss propagation through the beam pipeline uses the same accumulation rules as `.eh()`:
+
+```rust
+fn propagate<T, E, L: Loss>(loss: L, next: Imperfect<T, E, L>) -> Imperfect<T, E, L> {
+    match next {
+        Imperfect::Success(v) => Imperfect::partial(v, loss),
+        Imperfect::Partial(v, loss2) => Imperfect::partial(v, loss.combine(loss2)),
+        Imperfect::Failure(e, loss2) => Imperfect::failure_with_loss(e, loss.combine(loss2)),
+    }
+}
+```
+
 [Back to README](../README.md) · [Context →](context.md)