consensus_encoding: beef up module docs

diff --git a/consensus_encoding/src/decode/mod.rs b/consensus_encoding/src/decode/mod.rs
index e1d3e705..d1a16e4d 100644
--- a/consensus_encoding/src/decode/mod.rs
+++ b/consensus_encoding/src/decode/mod.rs
@@ -8,6 +8,35 @@ pub mod decoders;
 ///
 /// To decode something, create a [`Self::Decoder`] and push byte slices
 /// into it with [`Decoder::push_bytes`], then call [`Decoder::end`] to get the result.
+///
+/// # Examples
+///
+/// ```
+/// use bitcoin_consensus_encoding::{decode_from_slice, Decodable, Decoder, ArrayDecoder, UnexpectedEofError};
+///
+/// struct Foo([u8; 4]);
+///
+/// struct FooDecoder(ArrayDecoder<4>);
+///
+/// impl Decoder for FooDecoder {
+///     type Output = Foo;
+///     type Error = UnexpectedEofError;
+///
+///     fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
+///         self.0.push_bytes(bytes)
+///     }
+///     fn end(self) -> Result<Self::Output, Self::Error> { self.0.end().map(Foo) }
+///     fn read_limit(&self) -> usize { self.0.read_limit() }
+/// }
+///
+/// impl Decodable for Foo {
+///     type Decoder = FooDecoder;
+///     fn decoder() -> Self::Decoder { FooDecoder(ArrayDecoder::new()) }
+/// }
+///
+/// let foo: Foo = decode_from_slice(&[0xde, 0xad, 0xbe, 0xef]).unwrap();
+/// assert_eq!(foo.0, [0xde, 0xad, 0xbe, 0xef]);
+/// ```
 pub trait Decodable {
     /// Associated decoder for the type.
     type Decoder: Decoder<Output = Self>;
diff --git a/consensus_encoding/src/encode/mod.rs b/consensus_encoding/src/encode/mod.rs
index 84271b70..1c7766ba 100644
--- a/consensus_encoding/src/encode/mod.rs
+++ b/consensus_encoding/src/encode/mod.rs
@@ -12,6 +12,31 @@ pub mod encoders;
 /// To encode something, use the [`Self::encoder`] method to obtain a
 /// [`Self::Encoder`], which will behave like an iterator yielding
 /// byte slices.
+///
+/// # Examples
+///
+/// ```
+/// # #[cfg(feature = "alloc")] {
+/// use bitcoin_consensus_encoding::{encoder_newtype, encode_to_vec, Encodable, ArrayEncoder};
+///
+/// struct Foo([u8; 4]);
+///
+/// encoder_newtype! {
+///     pub struct FooEncoder<'e>(ArrayEncoder<4>);
+/// }
+///
+/// impl Encodable for Foo {
+///     type Encoder<'e> = FooEncoder<'e> where Self: 'e;
+///
+///     fn encoder(&self) -> Self::Encoder<'_> {
+///         FooEncoder::new(ArrayEncoder::without_length_prefix(self.0))
+///     }
+/// }
+///
+/// let foo = Foo([0xde, 0xad, 0xbe, 0xef]);
+/// assert_eq!(encode_to_vec(&foo), vec![0xde, 0xad, 0xbe, 0xef]);
+/// # }
+/// ```
 pub trait Encodable {
     /// The encoder associated with this type. Conceptually, the encoder is like
     /// an iterator which yields byte slices.
diff --git a/consensus_encoding/src/lib.rs b/consensus_encoding/src/lib.rs
index 0212e317..03a7f4a3 100644
--- a/consensus_encoding/src/lib.rs
+++ b/consensus_encoding/src/lib.rs
@@ -2,9 +2,48 @@
 
 //! # Rust Bitcoin - consensus encoding and decoding
 //!
-//! This library provides traits that can be used to encode/decode objects in a
-//! consensus-consistent way.
+//! Traits and utilities for encoding and decoding Bitcoin data types in a
+//! consensus-consistent way, using a *sans-I/O* architecture.
 //!
+//! Rather than reading from or writing to [`std::io::Read`]/[`std::io::Write`]
+//! traits directly, the codec types work with byte slices. This keeps codec logic
+//! I/O-agnostic, so the same implementation works in `no_std` environments, sync
+//! I/O, async I/O, and hash engines without duplicating logic or surfacing
+//! I/O errors in non-I/O contexts (e.g. when hashing an encoding).
+//!
+//! *Consensus* encoding is the canonical byte representation of Bitcoin data
+//! types used across the peer-to-peer network and transaction serialization.
+//! This crate only supports deterministic encoding and will never support
+//! types like floats whose encoding is non-deterministic or platform-dependent.
+//!
+//! # Encoding
+//!
+//! Types implement [`Encodable`] to produce an [`Encoder`], which yields encoded
+//! bytes in chunks via [`Encoder::current_chunk`] and [`Encoder::advance`]. The
+//! caller drives the process by pulling chunks until `advance` returns `false`.
+//!
+//! # Decoding
+//!
+//! Types implement [`Decodable`] to produce a [`Decoder`], which consumes bytes
+//! via [`Decoder::push_bytes`] until it signals completion by returning
+//! `Ok(false)`. The caller then calls [`Decoder::end`] to obtain the decoded
+//! value.
+//!
+//! Unlike encoding, decoding is fallible. Both `push_bytes` and `end` return
+//! `Result`. I/O errors are handled by the caller, keeping the codec logic
+//! I/O-agnostic.
+//!
+//! # Drivers
+//!
+//! This crate provides free functions which drive codecs for common I/O interfaces.
+//!
+//! * [`decode_from_read`] / [`encode_to_writer`] - std library.
+//! * [`decode_from_slice`] / [`encode_to_vec`] - Memory allocations.
+//!
+//! # Feature Flags
+//!
+//! * `std` - Enables std lib I/O driver functions and `std::error::Error` impls (implies `alloc`).
+//! * `alloc` - Enables [`encode_to_vec`], `Vec`-based decoders, and allocation-based helpers.
 
 #![no_std]
 // Coding conventions.