diff --git a/src/lib.rs b/src/lib.rs
index 7f13487..70f0970 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,8 +1,45 @@
-/// Rusty Wire library entry point.
-///
-/// Exposes the I/O-free application layer so that front-ends other than the
-/// bundled CLI (e.g. a future `iced` GUI or a test harness) can depend on
-/// this crate without pulling in CLI-specific logic.
+//! # Rusty Wire
+//!
+//! Wire-antenna length planning for ham radio, exposed as a library so front-ends
+//! other than the bundled CLI (e.g. an `iced` GUI, a bot, or a test harness) can
+//! reuse the I/O-free application layer.
+//!
+//! ## Getting started
+//!
+//! Build an [`AppConfig`], run it, and read the per-band results:
+//!
+//! ```
+//! use rusty_wire::prelude::*;
+//!
+//! let config = AppConfig::default();
+//! let results = run_calculation(config);
+//! for calc in &results.calculations {
+//!     println!("{}: half-wave {:.2} m", calc.band_name, calc.half_wave_m);
+//! }
+//!
+//! // Or render the same document the CLI/TUI print:
+//! let doc = results_display_document(&results);
+//! assert!(!doc.band_views.is_empty());
+//! ```
+//!
+//! Use [`run_calculation_checked`] instead of [`run_calculation`] to validate the
+//! configuration first (returns an [`AppError`] on invalid input).
+//!
+//! ## Public API and stability
+//!
+//! The **stable, semver-tracked** surface is re-exported from [`prelude`]. Prefer
+//! importing from there.
+//!
+//! The [`app`], [`bands`], [`calculations`], [`prefs`], and [`sessions`] modules
+//! are public for advanced use, but items *not* re-exported from [`prelude`] may
+//! change in minor releases. The [`tui`] module and the `run_tui` entry point are
+//! provided for embedding the terminal UI but are not part of the stable API. The
+//! CLI, export, NEC-export, and fnec-validation modules are private implementation
+//! details.
+//!
+//! Semantic-versioning policy: breaking changes to `prelude` items bump the major
+//! version; additive changes bump the minor version.
+
 pub mod app;
 pub(crate) mod band_presets;
 pub mod bands;
@@ -15,6 +52,26 @@ pub mod prefs;
 pub mod sessions;
 pub mod tui;
 
+/// The stable, semver-tracked public API. Import everything with
+/// `use rusty_wire::prelude::*;`.
+///
+/// Anything re-exported here is covered by the crate's semver policy; other
+/// public items may change in minor releases.
+pub mod prelude {
+    #[doc(no_inline)]
+    pub use crate::app::{
+        results_display_document, run_calculation, run_calculation_checked, AppConfig, AppError,
+        AppRequest, AppResponse, AppResults, CalcMode, ResultsDisplayDocument,
+    };
+    #[doc(no_inline)]
+    pub use crate::bands::{Band, BandType, ITURegion};
+    #[doc(no_inline)]
+    pub use crate::calculations::{
+        GroundClass, ImpedanceClass, NonResonantRecommendation, NonResonantSearchConfig,
+        OcfdSplitRecommendation, ResonantCompromise, TransformerRatio, WireCalculation,
+    };
+}
+
 /// Run the command-line interface with the given argument list.
 ///
 /// Returns `true` on success, `false` if any error prevented completion.