docs: pre-0.5.0 doc cleanup

README.md

@@ -95,7 +95,7 @@ Solvers are domain-agnostic and know nothing about what your model represents. O
 
 ```rust
 use twine_core::Observer;
-use twine_observers::{HasResidual, CanStopEarly};
+use twine_observers::traits::{HasResidual, CanStopEarly};
 
 /// Logs each iteration and stops early when the residual is good enough.
 struct GoodEnough { tolerance: f64, min_iters: usize, iter: usize }
@@ -126,7 +126,7 @@ let solution = bisection::solve(
 // solution.status = StoppedByObserver
 ```
 
-`GoodEnough` is not tied to bisection. It works with any solver whose events expose a residual and whose actions support early stopping. The real power shows up in domain-specific observers — for example, an observer that recognizes a thermodynamic constraint violation and tells the solver to search elsewhere, turning an unsolvable problem into a solvable one.
+`GoodEnough` is just an example, but notice what makes it work: it's generic over `E: HasResidual` and `A: CanStopEarly`, not over bisection specifically. Any observer written against capability traits like these works across all solvers that expose them, not just bisection. The real power shows up in domain-specific observers — for example, an observer that recognizes a thermodynamic constraint violation and tells the solver to search elsewhere, turning an unsolvable problem into a solvable one.
 
 ## Crates
 

crates/core/src/lib.rs

@@ -1,3 +1,15 @@
+//! Core traits and types for the Twine framework.
+//!
+//! This crate defines the shared abstractions that solvers, observers, and
+//! models build on:
+//!
+//! - [`Model`] — a callable that maps a typed input to a typed output
+//! - [`Snapshot`] — a captured input/output pair from a model call
+//! - [`Observer`] — receives solver events and optionally returns control actions
+//! - [`EquationProblem`], [`OptimizationProblem`], [`OdeProblem`] — problem
+//!   traits that adapt solver variables to model inputs and extract metrics from
+//!   outputs
+
 mod model;
 mod observer;
 mod problems;

crates/observers/src/lib.rs

@@ -23,8 +23,16 @@
 //!
 //! # Features
 //!
-//! - `plot` — Enables [`PlotObserver`] and [`ShowConfig`] for visualizing solver
-//!   behavior via egui. This feature adds dependencies on `eframe` and `egui_plot`.
+#![cfg_attr(
+    feature = "plot",
+    doc = "- `plot` — Enables [`PlotObserver`] and [`ShowConfig`] for visualizing solver \
+           behavior via egui. This feature adds dependencies on `eframe` and `egui_plot`."
+)]
+#![cfg_attr(
+    not(feature = "plot"),
+    doc = "- `plot` — Enables `PlotObserver` and `ShowConfig` for visualizing solver \
+           behavior via egui. This feature adds dependencies on `eframe` and `egui_plot`."
+)]
 //!
 //! [`Observer`]: twine_core::Observer
 //! [`HasResidual`]: traits::HasResidual

crates/solvers/src/equation.rs

@@ -1,3 +1,15 @@
+//! Solvers for equation problems — finding roots of systems of equations.
+//!
+//! An [`EquationProblem`] maps solver variables `x: [f64; N]` to model inputs,
+//! calls the model, and computes residuals. Solvers in this module drive those
+//! residuals toward zero.
+//!
+//! # Solvers
+//!
+//! - [`bisection`] — guaranteed convergence on a bracketed interval
+//!
+//! [`EquationProblem`]: twine_core::EquationProblem
+
 mod evaluate;
 
 pub use evaluate::{EvalError, EvaluateResult, Evaluation, evaluate};

crates/solvers/src/optimization.rs

@@ -1,3 +1,16 @@
+//! Solvers for optimization problems — minimizing or maximizing an objective.
+//!
+//! An [`OptimizationProblem`] maps solver variables `x: [f64; N]` to model
+//! inputs, calls the model, and extracts a scalar objective. Solvers in this
+//! module search for the `x` that minimizes or maximizes that objective.
+//!
+//! # Solvers
+//!
+//! - [`golden_section`] — derivative-free search over a bracketed interval for
+//!   unimodal functions
+//!
+//! [`OptimizationProblem`]: twine_core::OptimizationProblem
+
 mod evaluate;
 
 pub use evaluate::{EvalError, EvaluateResult, Evaluation, evaluate};