docs: complete the public API documentation contract

Closes the last open item in #25. `cargo clippy -W missing_errors_doc
-W missing_panics_doc -W must_use_candidate -W doc_markdown` went from 56
warnings to zero.

The 13 hand-written sections name the actual variants each function returns
rather than gesturing at "an error". Establishing that meant reading the error
paths — `Game::ranked` alone returns four distinct variants, and `record_draw`
can hit TieWithoutDrawProbability where `record_winner` provably cannot, since
a two-team decisive outcome has nothing to tie. Documenting those as
interchangeable would have been worse than leaving them undocumented, because
a reader would trust it.

Two existing doc comments already described panics in prose but not under a
`# Panics` heading, so neither rustdoc nor clippy surfaced them:
`Outcome::winner` and `EventBuilder::weights`. Both now carry the heading, and
`Outcome::winner` gained the note that it ties every loser, so `n >= 3` needs a
positive p_draw — the crate's easiest error to hit by accident.

The 43 mechanical fixes (31 `#[must_use]` on pure accessors, 11 missing
backticks) were applied with `cargo clippy --fix`. `#[must_use]` on Gaussian's
arithmetic and on `posteriors()` matters: discarding those results is always a
bug, and until now nothing said so.

Also documented why `[profile.release] debug = true` exists — cargo-flamegraph
needs the symbols, and library profile settings are ignored downstream, so it
reads as an oversight without the note.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5SYDExxL4vZgvunrcNSMc

src/gaussian.rs

@@ -18,6 +18,7 @@ pub struct Gaussian {
 
 impl Gaussian {
     /// Construct from mean and standard deviation.
+    #[must_use]
     pub const fn from_ms(mu: f64, sigma: f64) -> Self {
         if sigma == f64::INFINITY {
             Self { pi: 0.0, tau: 0.0 }
@@ -64,16 +65,19 @@ impl Gaussian {
     }
 
     #[inline]
+    #[must_use]
     pub fn pi(&self) -> f64 {
         self.pi
     }
 
     #[inline]
+    #[must_use]
     pub fn tau(&self) -> f64 {
         self.tau
     }
 
     #[inline]
+    #[must_use]
     pub fn mu(&self) -> f64 {
         // A non-positive precision is an improper (uninformative) Gaussian — its mean is
         // undefined. Treat it like `pi == 0` and return 0. EP message cancellation can land
@@ -102,6 +106,7 @@ impl Gaussian {
     }
 
     #[inline]
+    #[must_use]
     pub fn sigma(&self) -> f64 {
         // A non-positive precision is improper → infinite standard deviation. Guarding
         // `pi <= 0.0` (not just `== 0.0`) keeps `1.0 / pi.sqrt()` from returning NaN when EP
@@ -145,6 +150,7 @@ impl Gaussian {
     /// Used by within-game inference to stabilise oscillating fixed-point
     /// loops on hard graphs. `alpha = 1.0` returns `new` exactly;
     /// `alpha < 1.0` shrinks each per-step update.
+    #[must_use]
     pub fn damp_natural(self, new: Gaussian, alpha: f64) -> Gaussian {
         Gaussian::from_natural(
             alpha * new.pi() + (1.0 - alpha) * self.pi(),