diff --git a/Cargo.toml b/Cargo.toml
index 13f3e3f..21be02e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -16,6 +16,7 @@ categories = [
   "data-structures",
 ]
 exclude = ["/.github", "/.gitignore", "/tests", "*.png", "*.md"]
+readme = "README.md"
 
 [dependencies]
 bevy = { version = "0.15", optional = true }
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5c23a20
--- /dev/null
+++ b/README.md
@@ -0,0 +1,89 @@
+# Hexlab
+
+<!-- toc -->
+
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
+
+<!-- tocstop -->
+
+Hexlab is a Rust library for generating and manipulating hexagonal mazes.
+
+## Features
+
+- Create hexagonal mazes of configurable size
+- Customizable maze properties (radius, start position, seed)
+- Efficient bit-flag representation of walls for optimized memory usage
+- Multiple maze generation algorithms (WIP)
+- Maze builder pattern for easy and flexible maze creation
+
+## Installation
+
+Add `hexlab` as a dependency:
+
+```sh
+cargo add hexlab
+```
+
+## Getting Started
+
+```rust
+use hexlab::prelude::*;
+
+fn main() {
+    // Create a new maze with radius 5
+    let maze = MazeBuilder::new()
+        .with_radius(5)
+        .build()
+        .expect("Failed to create maze");
+    println!("Maze size: {}", maze.len());
+}
+```
+
+## Usage
+
+```rust
+use hexlab::prelude::*;
+
+// Create a new maze
+let maze = MazeBuilder::new()
+    .with_radius(5)
+    .build()
+    .expect("Failed to create maze");
+
+// Get a specific tile
+let tile = maze.get_tile(&Hex::new(1, -1)).unwrap();
+
+// Check if a wall exists
+let has_wall = tile.walls().contains(EdgeDirection::FLAT_NORTH);
+```
+
+## Documentation
+
+Full documentation is available at [docs.rs](https://docs.rs/hexlab).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Acknowledgements
+
+Hexlab relies on the excellent [hexx](https://github.com/ManevilleF/hexx)
+library for handling hexagonal grid mathematics, coordinates, and related
+operations. We're grateful for the robust foundation it provides for working
+with hexagonal grids.
+
+## License
+
+This project is dual-licensed under either:
+
+- MIT License ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
+
+at your option.
diff --git a/src/builder.rs b/src/builder.rs
index c20b4b6..2670165 100644
--- a/src/builder.rs
+++ b/src/builder.rs
@@ -168,8 +168,8 @@ impl MazeBuilder {
     ///
     /// // Should succeed with radius
     /// let result = MazeBuilder::new()
-    /// .with_radius(3)
-    /// .build();
+    ///     .with_radius(3)
+    ///     .build();
     /// assert!(result.is_ok());
     ///
     /// let maze = result.unwrap();
diff --git a/src/lib.rs b/src/lib.rs
index fd59fad..7dead81 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,38 @@
+//! Hexlab is a library for generating and manipulating hexagonal mazes.
+//!
+//! # Features
+//!
+//! - Create hexagonal mazes of configurable size
+//! - Customizable maze properties (radius, start position, seed)
+//! - Efficient bit-flag representation of walls
+//! - Multiple maze generation algorithms
+//! - Maze builder pattern for easy maze creation
+
+//!
+//! # Examples
+//!
+//! Here's a quick example to create a simple hexagonal maze:
+//!
+//!```
+//! use hexlab::prelude::*;
+//!
+//! // Create a new maze
+//! let maze = MazeBuilder::new()
+//!     .with_radius(5)
+//!     .build()
+//!     .expect("Failed to create maze");
+//!
+//! // Get a specific tile
+//! let tile = maze.get_tile(&Hex::new(1, -1)).unwrap();
+//!
+//! // Check if a wall exists
+//! let has_wall = tile.walls().contains(EdgeDirection::FLAT_NORTH);
+//!```
+//!
+//! # Acknowledgements
+//!
+//! Hexlab relies on the excellent [hexx](https://github.com/ManevilleF/hexx) library for handling
+//! hexagonal grid mathematics, coordinates, and related operations.
 mod builder;
 mod generator;
 mod hex_maze;
@@ -10,6 +45,7 @@ pub use hex_maze::HexMaze;
 pub use hex_tile::HexTile;
 pub use walls::Walls;
 
+/// Prelude module containing commonly used types
 pub mod prelude {
     pub use super::{GeneratorType, HexMaze, HexTile, MazeBuilder, MazeBuilderError, Walls};
     pub use hexx::{EdgeDirection, Hex, HexLayout};