diff --git a/src/lib.rs b/src/lib.rs
index 56679e6..ed09ffd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,55 @@
 //! alkgen: text-generation engine on handlebars-rust templates over serde-serializable contexts.
+//!
+//! The crate's whole public surface is three types:
+//!
+//! - [`TemplateSet`]: one registry per template set, strict mode forced
+//!   on, templates and partials registered from caller-supplied text
+//!   (there is no filesystem path), and the two render entry points.
+//! - [`EscapePolicy`]: the escaper chosen per set ([`EscapePolicy::Html`]
+//!   for HTML output, [`EscapePolicy::NoOp`] for code generation).
+//! - [`Error`]: the typed error data every failure path surfaces as.
+//!
+//! Rendering is synchronous, pure, and deterministic (ADR-003): the
+//! same registry contents plus the same context produce byte-identical
+//! output, which is what makes consumer-side caching and regression
+//! pins safe. Missing context variables fail typed under strict mode;
+//! they never render silently empty.
+//!
+//! # Example
+//!
+//! ```
+//! use alkgen::{EscapePolicy, TemplateSet};
+//! use serde_json::json;
+//!
+//! let mut set = TemplateSet::new(EscapePolicy::Html);
+//! set.register_template("page", "<h1>{{title}}</h1>{{> footer}}")
+//!     .expect("well-formed template registers");
+//! set.register_partial("footer", "<p>{{year}}</p>")
+//!     .expect("well-formed partial registers");
+//!
+//! let ctx = json!({ "title": "Hello", "year": "2026" });
+//! assert_eq!(
+//!     set.render("page", &ctx).expect("render succeeds"),
+//!     "<h1>Hello</h1><p>2026</p>"
+//! );
+//! ```
+//!
+//! The write sink renders the same bytes without the intermediate
+//! allocation:
+//!
+//! ```
+//! use alkgen::{EscapePolicy, TemplateSet};
+//! use serde_json::json;
+//!
+//! let mut set = TemplateSet::new(EscapePolicy::NoOp);
+//! set.register_template("line", "let x = {{value}};")
+//!     .expect("well-formed template registers");
+//!
+//! let mut sink = Vec::new();
+//! set.render_to_write("line", &json!({ "value": 7 }), &mut sink)
+//!     .expect("render succeeds");
+//! assert_eq!(String::from_utf8(sink).expect("utf-8"), "let x = 7;");
+//! ```
 
 mod error;
 mod escape;