diff --git a/src/client.rs b/src/client.rs
index c222b58..512b1a2 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -1,3 +1,18 @@
+/*!
+The `client` module provides a comprehensive interface for interacting with Supabase Authentication services.
+
+This module enables user authentication, session management, user administration, and server health monitoring
+through the [`AuthClient`] struct.
+
+# Notes
+
+- Some features require Supabase Pro plan subscription
+- OAuth and SSO require configuration in Supabase dashboard
+- Rate limiting may apply to authentication operations
+- Always use HTTPS in production environments
+- Properly handle token expiration and refresh cycles
+*/
+
 #![cfg(not(doctest))]
 
 use std::env;
@@ -23,7 +38,7 @@ use crate::{
 
 impl AuthClient {
     /// Create a new Auth Client
-    /// You can find your project url and keys at https://supabase.com/dashboard/project/<your project id>/settings/api
+    /// You can find your project url and keys at `https://supabase.com/dashboard/project/YOUR_PROJECT_ID/settings/api`
     /// # Example
     /// ```
     /// let auth_client = AuthClient::new(project_url, api_key, jwt_secret).unwrap();
diff --git a/src/error.rs b/src/error.rs
index 90ad563..4df3dfc 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,3 +1,12 @@
+/*!
+Provides error types and handling for Supabase authentication operations.
+
+This module defines the primary [`Error`] enum and supporting types for handling various
+error conditions that may occur during authentication operations.
+
+The most common error is [`Error::Supabase`] which wraps [`SupabaseHTTPError`]. This is a transparent error which gives you the `status` as a [`StatusCode`] and `message` from the Supabase response.
+*/
+
 use std::{
     env,
     fmt::{self, Display},
diff --git a/src/lib.rs b/src/lib.rs
index 5f89aa5..f2419d3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,139 @@
+/*!
+# Supabase Auth
+
+[![Crates.io License](https://img.shields.io/crates/l/supabase-auth?style=for-the-badge)](https://crates.io/crates/supabase-auth)
+[![Crates.io Version](https://img.shields.io/crates/v/supabase-auth?style=for-the-badge)](https://crates.io/crates/supabase-auth)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/proziam/supabase-auth-rs/rust.yml?branch=main&style=for-the-badge)](https://github.com/proziam/supabase-auth-rs)
+[![docs.rs](https://img.shields.io/docsrs/supabase-auth?style=for-the-badge)](https://docs.rs/supabase-auth/latest/supabase_auth/index.html)
+
+A Rust implementation of the [supabase js auth client](https://github.com/supabase/gotrue-js).
+The goal is to have feature parity and an easy-to-use API.
+
+Currently this software is functional, but not yet battle-tested. The goal is to go to 1.0.0
+by the end of December, 2024.
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+supabase-auth = "0.1.0"
+```
+
+Or use cargo-add:
+
+```bash
+cargo add supabase-auth
+```
+
+## Usage
+
+### Create an Auth Client
+
+```rust
+// You can manually pass in the values
+let auth_client = AuthClient::new(project_url, api_key, jwt_secret).unwrap();
+
+// Or you can use environment variables
+// Requires `SUPABASE_URL`, `SUPABASE_API_KEY`, and `SUPABASE_JWT_SECRET` environment variables
+let auth_client = AuthClient::new_from_env().unwrap();
+```
+
+### Sign Up
+
+```rust
+// Sign up methods return the session which you can use for creating cookies
+let session = auth_client
+    .sign_up_with_email_and_password(demo_email, demo_password)
+    .await
+    .unwrap();
+
+// You can also sign up using a phone number and password
+let session = auth_client
+    .sign_up_with_phone_and_password(demo_phone, demo_password)
+    .await
+    .unwrap();
+```
+
+### Sign In
+
+```rust
+// Sign in methods return the session which you can use for creating cookies
+let session = auth_client
+    .login_with_email(&demo_email, &demo_password)
+    .await
+    .unwrap();
+
+// You can also login using a phone number
+let session = auth_client
+    .login_with_phone(demo_phone, demo_password)
+    .await
+    .unwrap();
+```
+
+### OAuth
+
+```rust
+// Returns the provider and the url where the user will continue the auth flow
+let oauth_response = auth_client
+    .login_with_oauth(Provider::Github, None)
+    .await
+    .unwrap();
+
+// You can also customize the options like so:
+let mut query_params = HashMap::new();
+query_params.insert("key".to_string(), "value".to_string());
+query_params.insert("second_key".to_string(), "second_value".to_string());
+query_params.insert("third_key".to_string(), "third_value".to_string());
+
+let options = SignInWithOAuthOptions {
+    query_params: Some(query_params),
+    redirect_to: Some("your-redirect-url".to_string()),
+    scopes: Some("repo gist notifications".to_string()),
+    skip_brower_redirect: Some(true),
+};
+
+let response = auth_client
+    .login_with_oauth(Provider::Github, Some(options))
+    .await
+    .unwrap();
+```
+
+### SSO
+
+NOTE: Requires an SSO Provider and Supabase Pro plan
+
+```rust
+let params = SignInWithSSO {
+    domain: Some(demo_domain),
+    options: None,
+    provider_id: None,
+};
+
+// Returns the URL where the user will continue the auth flow with your SSO provider
+let url = auth_client.sso(params).await.unwrap();
+```
+
+## Features
+
+* ✓ Create Client
+* ✓ Sign In with Email & Password
+* ✓ Sign In with Phone & Password
+* ✓ Sign Up with Email & Password
+* ✓ Sign Up with Phone & Password
+* ✓ Sign In with Third Party Auth (OAuth)
+* ✓ Sign In with Magic Link
+* ✓ Send Sign-In OTP (Email, SMS, Whatsapp)
+* ✓ Sign In with OTP
+* ✓ Refresh Session
+* ✓ Resend OTP Tokens (Email & SMS)
+* ✓ Retrieve User
+* ✓ Reset Password
+* ✓ Change User Data (e.g., Email or password)
+* ✓ SSO
+*/
+
 #![forbid(unsafe_code)]
 #![deny(missing_debug_implementations)]
 
diff --git a/src/models.rs b/src/models.rs
index f8f7918..9a48390 100644
--- a/src/models.rs
+++ b/src/models.rs
@@ -10,7 +10,7 @@ use std::{collections::HashMap, fmt::Display};
 pub struct AuthClient {
     pub(crate) client: Client,
     /// REST endpoint for querying and managing your database
-    /// Example: https://<project id>.supabase.co
+    /// Example: `https://YOUR_PROJECT_ID.supabase.co`
     pub(crate) project_url: String,
     /// WARN: The `service role` key has the ability to bypass Row Level Security. Never share it publicly.
     pub(crate) api_key: String,