diff --git a/crates/cfsctl/src/main.rs b/crates/cfsctl/src/main.rs
index 0fabcb2d..1b575afb 100644
--- a/crates/cfsctl/src/main.rs
+++ b/crates/cfsctl/src/main.rs
@@ -1,3 +1,9 @@
+//! Command-line control utility for composefs repositories and images.
+//!
+//! `cfsctl` provides a comprehensive interface for managing composefs repositories,
+//! creating and mounting filesystem images, handling OCI containers, and performing
+//! repository maintenance operations like garbage collection.
+
 use std::{
     fs::create_dir_all,
     path::{Path, PathBuf},
diff --git a/crates/composefs-boot/src/bootloader.rs b/crates/composefs-boot/src/bootloader.rs
index 421b4877..bf5cab14 100644
--- a/crates/composefs-boot/src/bootloader.rs
+++ b/crates/composefs-boot/src/bootloader.rs
@@ -1,3 +1,11 @@
+//! Bootloader entry parsing and manipulation.
+//!
+//! This module provides functionality to parse and manipulate Boot Loader Specification
+//! entries and Unified Kernel Images (UKIs). It supports Type 1 BLS entries with separate
+//! kernel and initrd files, Type 2 UKI files, and traditional vmlinuz/initramfs pairs
+//! from /usr/lib/modules. Key types include `BootLoaderEntryFile` for parsing BLS
+//! configuration files and `BootEntry` enum for representing different boot entry types.
+
 use core::ops::Range;
 use std::{
     collections::HashMap, ffi::OsStr, os::unix::ffi::OsStrExt, path::PathBuf, str::from_utf8,
diff --git a/crates/composefs-boot/src/cmdline.rs b/crates/composefs-boot/src/cmdline.rs
index 55be01b4..a73c8aab 100644
--- a/crates/composefs-boot/src/cmdline.rs
+++ b/crates/composefs-boot/src/cmdline.rs
@@ -1,3 +1,10 @@
+//! Kernel command line parsing and manipulation.
+//!
+//! This module provides utilities for parsing and generating kernel command line arguments,
+//! with specific support for composefs parameters. It handles the kernel's simple quoting
+//! mechanism and provides functions to extract and create composefs= arguments with optional
+//! insecure mode indicators.
+
 use anyhow::{Context, Result};
 use composefs::fsverity::FsVerityHashValue;
 
diff --git a/crates/composefs-boot/src/lib.rs b/crates/composefs-boot/src/lib.rs
index 1629cedf..791c40d4 100644
--- a/crates/composefs-boot/src/lib.rs
+++ b/crates/composefs-boot/src/lib.rs
@@ -1,3 +1,10 @@
+//! Boot integration for composefs filesystem images.
+//!
+//! This crate provides functionality to transform composefs filesystem images for boot
+//! scenarios by extracting boot resources, applying SELinux labels, and preparing
+//! bootloader entries. It supports both Boot Loader Specification (Type 1) entries
+//! and Unified Kernel Images (Type 2) for UEFI boot.
+
 #![deny(missing_debug_implementations)]
 
 pub mod bootloader;
diff --git a/crates/composefs-boot/src/os_release.rs b/crates/composefs-boot/src/os_release.rs
index dbf686b2..9a9a8bc2 100644
--- a/crates/composefs-boot/src/os_release.rs
+++ b/crates/composefs-boot/src/os_release.rs
@@ -1,3 +1,10 @@
+//! Parsing and handling of os-release files.
+//!
+//! This module provides functionality to parse os-release files according to the
+//! freedesktop.org specification. It handles shell-style quoting and variable assignment,
+//! extracting common fields like PRETTY_NAME, VERSION_ID, and ID for use in boot labels.
+//! The `OsReleaseInfo` type provides methods to generate appropriate boot entry titles.
+
 use std::collections::HashMap;
 
 // We could be using 'shlex' for this but we really only need to parse a subset of the spec and
diff --git a/crates/composefs-boot/src/selabel.rs b/crates/composefs-boot/src/selabel.rs
index 0e879ad7..77665120 100644
--- a/crates/composefs-boot/src/selabel.rs
+++ b/crates/composefs-boot/src/selabel.rs
@@ -1,3 +1,10 @@
+//! SELinux security context labeling for filesystem trees.
+//!
+//! This module implements SELinux policy parsing and file labeling functionality.
+//! It reads SELinux policy files (file_contexts, file_contexts.subs, etc.) and applies
+//! appropriate security.selinux extended attributes to filesystem nodes. The implementation
+//! uses regex automata for efficient pattern matching against file paths and types.
+
 use std::{
     collections::HashMap,
     ffi::{OsStr, OsString},
diff --git a/crates/composefs-boot/src/uki.rs b/crates/composefs-boot/src/uki.rs
index 9a7a3831..3aee5e59 100644
--- a/crates/composefs-boot/src/uki.rs
+++ b/crates/composefs-boot/src/uki.rs
@@ -1,3 +1,10 @@
+//! Unified Kernel Image (UKI) parsing and metadata extraction.
+//!
+//! This module provides functionality to parse PE (Portable Executable) format UKI files
+//! and extract embedded sections like .osrel and .cmdline. It implements the Boot Loader
+//! Specification Type 2 requirements for UKI boot entries, including extraction of boot
+//! labels from os-release information embedded in the UKI binary.
+
 use thiserror::Error;
 use zerocopy::{
     little_endian::{U16, U32},
diff --git a/crates/composefs-boot/src/write_boot.rs b/crates/composefs-boot/src/write_boot.rs
index 5605cc73..46b54ce7 100644
--- a/crates/composefs-boot/src/write_boot.rs
+++ b/crates/composefs-boot/src/write_boot.rs
@@ -1,3 +1,10 @@
+//! Boot entry writing and installation functionality.
+//!
+//! This module provides functions to write boot entries to the filesystem, handling both
+//! Boot Loader Specification Type 1 entries (separate kernel/initrd files) and Type 2
+//! Unified Kernel Images. It manages file placement, directory creation, and command line
+//! argument injection for composefs boot scenarios.
+
 use std::{
     fs::{create_dir_all, write},
     path::Path,
diff --git a/crates/composefs-fuse/src/lib.rs b/crates/composefs-fuse/src/lib.rs
index 6fa54133..351a4e5b 100644
--- a/crates/composefs-fuse/src/lib.rs
+++ b/crates/composefs-fuse/src/lib.rs
@@ -1,3 +1,9 @@
+//! FUSE filesystem implementation for composefs trees.
+//!
+//! This crate provides a userspace filesystem implementation that exposes composefs
+//! directory trees through FUSE. It supports read-only access to files, directories,
+//! symlinks, and extended attributes, with data served from a composefs repository.
+
 use std::{
     collections::HashMap,
     ffi::OsStr,
diff --git a/crates/composefs-http/src/lib.rs b/crates/composefs-http/src/lib.rs
index 1d983876..666e69cb 100644
--- a/crates/composefs-http/src/lib.rs
+++ b/crates/composefs-http/src/lib.rs
@@ -1,3 +1,9 @@
+//! HTTP-based download functionality for composefs splitstreams and objects.
+//!
+//! This crate provides an asynchronous downloader that can fetch splitstreams and their
+//! referenced objects from HTTP servers. It handles recursive fetching of nested splitstream
+//! references and verifies content integrity using fsverity checksums.
+
 use std::{
     collections::{HashMap, HashSet},
     fs::File,
diff --git a/crates/composefs-oci/src/image.rs b/crates/composefs-oci/src/image.rs
index 93c8c756..53e9d6b1 100644
--- a/crates/composefs-oci/src/image.rs
+++ b/crates/composefs-oci/src/image.rs
@@ -1,3 +1,13 @@
+//! OCI image processing and filesystem construction.
+//!
+//! This module handles the conversion of OCI container image layers into composefs filesystems.
+//! It processes tar entries from container layers, handles overlayfs semantics like whiteouts,
+//! and constructs the final filesystem tree that can be mounted or analyzed.
+//!
+//! The main functionality centers around `create_filesystem()` which takes an OCI image configuration
+//! and builds a complete filesystem by processing all layers in order. The `process_entry()` function
+//! handles individual tar entries and implements overlayfs whiteout semantics for proper layer merging.
+
 use std::{ffi::OsStr, os::unix::ffi::OsStrExt, rc::Rc};
 
 use anyhow::{ensure, Context, Result};
diff --git a/crates/composefs-oci/src/lib.rs b/crates/composefs-oci/src/lib.rs
index 6e77de29..560b9fe8 100644
--- a/crates/composefs-oci/src/lib.rs
+++ b/crates/composefs-oci/src/lib.rs
@@ -1,3 +1,15 @@
+//! OCI container image support for composefs.
+//!
+//! This crate provides functionality for working with OCI (Open Container Initiative) container images
+//! in the context of composefs. It enables importing, extracting, and mounting container images as
+//! composefs filesystems with fs-verity integrity protection.
+//!
+//! Key functionality includes:
+//! - Pulling container images from registries using skopeo
+//! - Converting OCI image layers from tar format to composefs split streams
+//! - Creating mountable filesystems from OCI image configurations
+//! - Sealing containers with fs-verity hashes for integrity verification
+
 pub mod image;
 pub mod skopeo;
 pub mod tar;
diff --git a/crates/composefs-oci/src/skopeo.rs b/crates/composefs-oci/src/skopeo.rs
index a184d372..de40e994 100644
--- a/crates/composefs-oci/src/skopeo.rs
+++ b/crates/composefs-oci/src/skopeo.rs
@@ -1,3 +1,13 @@
+//! Container image pulling and registry interaction via skopeo/containers-image-proxy.
+//!
+//! This module provides functionality to pull container images from various registries and import them
+//! into composefs repositories. It uses the containers-image-proxy library to interface with skopeo
+//! for image operations, handling authentication, transport protocols, and image manifest processing.
+//!
+//! The main entry point is the `pull()` function which downloads an image, processes its layers
+//! asynchronously with parallelism control, and stores them in the composefs repository with proper
+//! fs-verity integration. It supports various image formats and compression types.
+
 use std::{cmp::Reverse, process::Command, thread::available_parallelism};
 
 use std::{iter::zip, sync::Arc};
diff --git a/crates/composefs-oci/src/tar.rs b/crates/composefs-oci/src/tar.rs
index 6ea651be..c1f056c9 100644
--- a/crates/composefs-oci/src/tar.rs
+++ b/crates/composefs-oci/src/tar.rs
@@ -1,3 +1,14 @@
+//! TAR archive processing and split stream conversion.
+//!
+//! This module handles the conversion of tar archives (container image layers) into composefs split streams.
+//! It provides both synchronous and asynchronous tar processing, intelligently deciding whether to store
+//! file content inline in the split stream or externally in the object store based on file size.
+//!
+//! Key components include the `split()` and `split_async()` functions for converting tar streams,
+//! `get_entry()` for reading back tar entries from split streams, and comprehensive support for
+//! tar format features including GNU long names, PAX extensions, and various file types.
+//! The `TarEntry` and `TarItem` types represent processed tar entries in composefs format.
+
 use std::{
     cell::RefCell,
     collections::BTreeMap,
diff --git a/crates/composefs-setup-root/src/main.rs b/crates/composefs-setup-root/src/main.rs
index 3d41917c..eda8de7c 100644
--- a/crates/composefs-setup-root/src/main.rs
+++ b/crates/composefs-setup-root/src/main.rs
@@ -1,3 +1,9 @@
+//! Root filesystem setup utility for composefs-based boot systems.
+//!
+//! This utility is designed to run during early boot to mount and configure
+//! the root filesystem using composefs images. It handles overlay mounts for
+//! writable directories, state management, and system integration.
+
 use std::{
     ffi::OsString,
     fmt::Debug,
diff --git a/crates/composefs/src/dumpfile.rs b/crates/composefs/src/dumpfile.rs
index 4a2b8b1a..4a213dc7 100644
--- a/crates/composefs/src/dumpfile.rs
+++ b/crates/composefs/src/dumpfile.rs
@@ -1,3 +1,9 @@
+//! Writing composefs dumpfile format from filesystem trees.
+//!
+//! This module provides functionality to serialize filesystem trees into
+//! the composefs dumpfile text format, handling file metadata, extended
+//! attributes, and hardlink tracking.
+
 use std::{
     collections::HashMap,
     ffi::{OsStr, OsString},
diff --git a/crates/composefs/src/erofs/composefs.rs b/crates/composefs/src/erofs/composefs.rs
index b293bf60..4fc2e4ef 100644
--- a/crates/composefs/src/erofs/composefs.rs
+++ b/crates/composefs/src/erofs/composefs.rs
@@ -1,3 +1,8 @@
+//! Composefs-specific EROFS structures and overlay metadata.
+//!
+//! This module defines EROFS structures specific to composefs usage,
+//! particularly overlay metadata for fs-verity integration.
+
 use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
 
 use crate::fsverity::FsVerityHashValue;
diff --git a/crates/composefs/src/erofs/debug.rs b/crates/composefs/src/erofs/debug.rs
index a938fc88..f4b17ac8 100644
--- a/crates/composefs/src/erofs/debug.rs
+++ b/crates/composefs/src/erofs/debug.rs
@@ -1,3 +1,8 @@
+//! Debug utilities for analyzing EROFS images.
+//!
+//! This module provides tools for inspecting and debugging EROFS filesystem
+//! images, including detailed structure dumping and space usage analysis.
+
 use std::{
     cmp::Ordering,
     collections::BTreeMap,
diff --git a/crates/composefs/src/erofs/format.rs b/crates/composefs/src/erofs/format.rs
index 8530f29b..fa5a99c9 100644
--- a/crates/composefs/src/erofs/format.rs
+++ b/crates/composefs/src/erofs/format.rs
@@ -1,3 +1,9 @@
+//! EROFS on-disk format definitions and data structures.
+//!
+//! This module defines the binary layout of EROFS filesystem structures
+//! including superblocks, inodes, directory entries, and other metadata
+//! using safe zerocopy-based parsing.
+
 // This is currently implemented using zerocopy but the eventual plan is to do this with safe
 // transmutation.  As such: all of the structures are defined in terms of pure LE integer sizes, we
 // handle the conversion to enum values separately, and we avoid the TryFromBytes trait.
diff --git a/crates/composefs/src/erofs/mod.rs b/crates/composefs/src/erofs/mod.rs
index fac88cd5..b86fb8b9 100644
--- a/crates/composefs/src/erofs/mod.rs
+++ b/crates/composefs/src/erofs/mod.rs
@@ -1,3 +1,8 @@
+//! EROFS (Enhanced Read-Only File System) format support for composefs.
+//!
+//! This module provides functionality to read and write EROFS filesystem images,
+//! which are used as the underlying storage format for composefs images.
+
 pub mod composefs;
 pub mod debug;
 pub mod format;
diff --git a/crates/composefs/src/erofs/reader.rs b/crates/composefs/src/erofs/reader.rs
index 10cdcb70..dff97bae 100644
--- a/crates/composefs/src/erofs/reader.rs
+++ b/crates/composefs/src/erofs/reader.rs
@@ -1,3 +1,9 @@
+//! EROFS image reading and parsing functionality.
+//!
+//! This module provides safe parsing and navigation of EROFS filesystem
+//! images, including inode traversal, directory reading, and object
+//! reference collection for garbage collection.
+
 use core::mem::size_of;
 use std::collections::{BTreeSet, HashSet};
 use std::ops::Range;
diff --git a/crates/composefs/src/erofs/writer.rs b/crates/composefs/src/erofs/writer.rs
index 5dfc9e48..bf60fcbc 100644
--- a/crates/composefs/src/erofs/writer.rs
+++ b/crates/composefs/src/erofs/writer.rs
@@ -1,3 +1,9 @@
+//! EROFS image generation and writing functionality.
+//!
+//! This module provides functionality to generate EROFS filesystem images
+//! from composefs tree structures, handling inode layout, directory blocks,
+//! and metadata serialization.
+
 use std::{
     cell::RefCell,
     collections::{BTreeMap, HashMap},
diff --git a/crates/composefs/src/filesystem_ops.rs b/crates/composefs/src/filesystem_ops.rs
index c40bdcf7..9ba94c16 100644
--- a/crates/composefs/src/filesystem_ops.rs
+++ b/crates/composefs/src/filesystem_ops.rs
@@ -1,3 +1,9 @@
+//! High-level filesystem operations for composefs trees.
+//!
+//! This module provides convenience methods for common operations on
+//! FileSystem objects, including computing image IDs, committing to
+//! repositories, and generating dumpfiles.
+
 use anyhow::Result;
 
 use crate::{
diff --git a/crates/composefs/src/fs.rs b/crates/composefs/src/fs.rs
index 2bafeba2..9583007d 100644
--- a/crates/composefs/src/fs.rs
+++ b/crates/composefs/src/fs.rs
@@ -1,3 +1,9 @@
+//! Reading and writing filesystem trees to/from disk.
+//!
+//! This module provides functionality to read filesystem structures from
+//! disk into composefs tree representations and write them back, including
+//! handling of hardlinks, extended attributes, and repository integration.
+
 use std::{
     cell::RefCell,
     collections::{BTreeMap, HashMap},
diff --git a/crates/composefs/src/fsverity/digest.rs b/crates/composefs/src/fsverity/digest.rs
index 861fc92c..3a784e50 100644
--- a/crates/composefs/src/fsverity/digest.rs
+++ b/crates/composefs/src/fsverity/digest.rs
@@ -1,3 +1,8 @@
+//! Userspace fs-verity digest computation.
+//!
+//! This module implements the fs-verity Merkle tree algorithm in userspace,
+//! allowing computation of fs-verity digests without kernel support.
+
 use core::{cmp::min, mem::size_of};
 
 use sha2::Digest;
diff --git a/crates/composefs/src/fsverity/hashvalue.rs b/crates/composefs/src/fsverity/hashvalue.rs
index 5cfb6d71..b7ff5a03 100644
--- a/crates/composefs/src/fsverity/hashvalue.rs
+++ b/crates/composefs/src/fsverity/hashvalue.rs
@@ -1,3 +1,9 @@
+//! Hash value types and trait definitions for fs-verity.
+//!
+//! This module defines the FsVerityHashValue trait and concrete implementations
+//! for SHA-256 and SHA-512 hash values, including parsing from hex strings
+//! and object pathnames.
+
 use core::{fmt, hash::Hash};
 
 use hex::FromHexError;
diff --git a/crates/composefs/src/fsverity/ioctl.rs b/crates/composefs/src/fsverity/ioctl.rs
index 20f6086b..67ce19b5 100644
--- a/crates/composefs/src/fsverity/ioctl.rs
+++ b/crates/composefs/src/fsverity/ioctl.rs
@@ -1,3 +1,9 @@
+//! Low-level ioctl interfaces for fs-verity kernel operations.
+//!
+//! This module provides safe wrappers around the Linux fs-verity ioctls
+//! for enabling and measuring fs-verity on files, handling the conversion
+//! between kernel and userspace data structures.
+
 #![allow(unsafe_code)]
 
 use core::mem::size_of;
diff --git a/crates/composefs/src/fsverity/mod.rs b/crates/composefs/src/fsverity/mod.rs
index 367fc9c8..c10cbb53 100644
--- a/crates/composefs/src/fsverity/mod.rs
+++ b/crates/composefs/src/fsverity/mod.rs
@@ -1,3 +1,9 @@
+//! Linux fs-verity support for integrity verification.
+//!
+//! This module provides complete fs-verity functionality including userspace
+//! digest computation, kernel ioctl interfaces for enabling and measuring
+//! verity, and hash value types for SHA-256 and SHA-512.
+
 mod digest;
 mod hashvalue;
 mod ioctl;
diff --git a/crates/composefs/src/lib.rs b/crates/composefs/src/lib.rs
index bc4f9500..ade99c27 100644
--- a/crates/composefs/src/lib.rs
+++ b/crates/composefs/src/lib.rs
@@ -1,3 +1,9 @@
+//! Rust bindings and utilities for working with composefs images and repositories.
+//!
+//! Composefs is a read-only FUSE filesystem that enables efficient sharing
+//! of container filesystem layers by using content-addressable storage
+//! and fs-verity for integrity verification.
+
 pub mod dumpfile;
 pub mod dumpfile_parse;
 pub mod erofs;
diff --git a/crates/composefs/src/mount.rs b/crates/composefs/src/mount.rs
index c97c554c..edbec2ff 100644
--- a/crates/composefs/src/mount.rs
+++ b/crates/composefs/src/mount.rs
@@ -1,3 +1,9 @@
+//! Modern Linux mount API support for composefs.
+//!
+//! This module provides functionality to mount composefs images using the
+//! new mount API (fsopen/fsmount) with overlay filesystem support and
+//! fs-verity verification.
+
 use std::{
     io::Result,
     os::fd::{AsFd, BorrowedFd, OwnedFd},
diff --git a/crates/composefs/src/mountcompat.rs b/crates/composefs/src/mountcompat.rs
index 009ce368..930e1c9a 100644
--- a/crates/composefs/src/mountcompat.rs
+++ b/crates/composefs/src/mountcompat.rs
@@ -1,3 +1,9 @@
+//! Compatibility helpers for older Linux kernel mount APIs.
+//!
+//! This module provides fallback implementations for mount operations
+//! on kernels that don't support the modern mount API, including
+//! loopback device setup and temporary mount handling.
+
 use std::{
     io::Result,
     os::fd::{AsFd, BorrowedFd, OwnedFd},
diff --git a/crates/composefs/src/repository.rs b/crates/composefs/src/repository.rs
index bc7652f0..679ed665 100644
--- a/crates/composefs/src/repository.rs
+++ b/crates/composefs/src/repository.rs
@@ -1,3 +1,9 @@
+//! Content-addressable repository for composefs objects.
+//!
+//! This module provides a repository abstraction for storing and retrieving
+//! content-addressed objects, splitstreams, and images with fs-verity
+//! verification and garbage collection support.
+
 use std::{
     collections::HashSet,
     ffi::CStr,
diff --git a/crates/composefs/src/splitstream.rs b/crates/composefs/src/splitstream.rs
index fe50cf4d..6b863016 100644
--- a/crates/composefs/src/splitstream.rs
+++ b/crates/composefs/src/splitstream.rs
@@ -1,3 +1,9 @@
+//! Split Stream file format implementation.
+//!
+//! This module implements the Split Stream format for efficiently storing
+//! and transferring data with inline content and external object references,
+//! supporting compression and content deduplication.
+
 /* Implementation of the Split Stream file format
  *
  * See doc/splitstream.md
diff --git a/crates/composefs/src/util.rs b/crates/composefs/src/util.rs
index 9f5fb13d..88f7809e 100644
--- a/crates/composefs/src/util.rs
+++ b/crates/composefs/src/util.rs
@@ -1,3 +1,9 @@
+//! Utility functions and types used throughout the composefs crate.
+//!
+//! This module provides common functionality including error handling helpers,
+//! I/O utilities for reading data streams, SHA256 digest parsing, and
+//! filesystem operations like atomic symlink replacement.
+
 use rand::{distr::Alphanumeric, Rng};
 use std::{
     io::{Error, ErrorKind, Read, Result},
diff --git a/crates/erofs-debug/src/main.rs b/crates/erofs-debug/src/main.rs
index 1ffd3788..fc5912e0 100644
--- a/crates/erofs-debug/src/main.rs
+++ b/crates/erofs-debug/src/main.rs
@@ -1,3 +1,9 @@
+//! Debug utility for analyzing EROFS filesystem images.
+//!
+//! This tool produces detailed, diff-friendly dumps of EROFS images that can be used
+//! to examine the internal structure and identify differences between images.
+//! The output format is deterministic and suitable for automated comparison.
+
 use std::{fs::File, io::Read, path::PathBuf};
 
 use clap::Parser;