diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..05ea955
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,5 @@
+# Welcome to Disagreement
+
+This is the official documentation for the Disagreement library.
+
+To get started, check out the [User Guide](introduction.md) or browse the [API Reference](http_client.md).
\ No newline at end of file
diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 0000000..4ba72c2
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,183 @@
+# Disagreement
+
+A Python library for interacting with the Discord API, with a focus on bot development.
+
+## Features
+
+- Asynchronous design using `aiohttp`
+- Gateway and HTTP API clients
+- Slash command framework
+- Message component helpers
+- Built-in caching layer
+- Experimental voice support
+- Helpful error handling utilities
+
+## Installation
+
+```bash
+python -m pip install -U pip
+pip install disagreement
+# or install from source for development
+pip install -e .
+```
+
+Requires Python 3.10 or newer.
+
+To run the example scripts, you'll need the `python-dotenv` package to load
+environment variables. Install the development extras with:
+
+```bash
+pip install "disagreement[dev]"
+```
+
+## Basic Usage
+
+```python
+import asyncio
+import os
+
+import disagreement
+from disagreement.ext import commands
+from dotenv import load_dotenv
+load_dotenv()
+
+
+class Basics(commands.Cog):
+    def __init__(self, client: disagreement.Client) -> None:
+        super().__init__(client)
+
+    @commands.command()
+    async def ping(self, ctx: commands.CommandContext) -> None:
+        await ctx.reply(f"Pong! Gateway Latency: {self.client.latency_ms} ms.")
+
+
+token = os.getenv("DISCORD_BOT_TOKEN")
+if not token:
+    raise RuntimeError("DISCORD_BOT_TOKEN environment variable not set")
+
+intents = disagreement.GatewayIntent.default() | disagreement.GatewayIntent.MESSAGE_CONTENT
+client = disagreement.Client(token=token, command_prefix="!", intents=intents, mention_replies=True)
+async def main() -> None:
+    client.add_cog(Basics(client))
+    await client.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Global Error Handling
+
+To ensure unexpected errors don't crash your bot, you can enable the library's
+global error handler:
+
+```python
+import disagreement
+
+disagreement.setup_global_error_handler()
+```
+
+Call this early in your program to log unhandled exceptions instead of letting
+them terminate the process.
+
+### Configuring Logging
+
+Use :func:`disagreement.logging_config.setup_logging` to configure logging for
+your bot. The helper accepts a logging level and an optional file path.
+
+```python
+import logging
+from disagreement.logging_config import setup_logging
+
+setup_logging(logging.INFO)
+# Or log to a file
+setup_logging(logging.DEBUG, file="bot.log")
+```
+
+### HTTP Session Options
+
+Pass additional keyword arguments to ``aiohttp.ClientSession`` using the
+``http_options`` parameter when constructing :class:`disagreement.Client`:
+
+```python
+client = disagreement.Client(
+    token=token,
+    http_options={"proxy": "http://localhost:8080"},
+)
+```
+
+These options are forwarded to ``HTTPClient`` when it creates the underlying
+``aiohttp.ClientSession``. You can specify a custom ``connector`` or any other
+session parameter supported by ``aiohttp``.
+
+### Default Allowed Mentions
+
+Specify default mention behaviour for all outgoing messages when constructing the client:
+
+```python
+client = disagreement.Client(
+    token=token,
+    allowed_mentions={"parse": [], "replied_user": False},
+)
+```
+
+This dictionary is used whenever ``send_message`` is called without an explicit
+``allowed_mentions`` argument.
+
+### Defining Subcommands with `AppCommandGroup`
+
+```python
+from disagreement.ext.app_commands import AppCommandGroup, slash_command
+from disagreement.ext.app_commands.context import AppCommandContext
+
+settings_group = AppCommandGroup("settings", "Manage settings")
+admin_group = AppCommandGroup("admin", "Admin settings", parent=settings_group)
+
+
+@slash_command(name="show", description="Display a setting.", parent=settings_group)
+async def show(ctx: AppCommandContext, key: str):
+    ...
+
+
+@slash_command(name="set", description="Update a setting.", parent=admin_group)
+async def set_setting(ctx: AppCommandContext, key: str, value: str):
+    ...
+```
+## Fetching Guilds
+
+Use `Client.fetch_guild` to retrieve a guild from the Discord API if it
+isn't already cached. This is useful when working with guild IDs from
+outside the gateway events.
+
+```python
+guild = await client.fetch_guild("123456789012345678")
+roles = await client.fetch_roles(guild.id)
+```
+
+## Sharding
+
+To run your bot across multiple gateway shards, pass ``shard_count`` when creating
+the client:
+
+```python
+client = disagreement.Client(token=BOT_TOKEN, shard_count=2)
+```
+
+If you want the a to determine the recommended shard count automatically,
+use ``AutoShardedClient``:
+
+```python
+client = disagreement.AutoShardedClient(token=BOT_TOKEN)
+```
+
+See `examples/sharded_bot.py` for a full example.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+See the [documentation home](index.md) for detailed guides on components, slash commands, caching, and voice features.
+
+## License
+
+This project is licensed under the BSD 3-Clause license. See the [LICENSE](https://github.com/your-username/disagreement/blob/main/LICENSE) file for details.
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..1dca2d4
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,63 @@
+site_name: Disagreement Docs
+site_description: 'Documentation for the Disagreement library.'
+repo_url: https://github.com/Slipstreamm/disagreement # Replace with your repo URL
+edit_uri: "" # Optional: link to edit page in repo
+
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: en
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+nav:
+  - 'Home': 'index.md'
+  - 'User Guide':
+    - 'Introduction': 'introduction.md'
+    - 'Getting Started':
+      - 'Slash Commands': 'slash_commands.md'
+      - 'Events': 'events.md'
+      - 'Components': 'using_components.md'
+      - 'Embeds': 'embeds.md'
+      - 'Context Menus': 'context_menus.md'
+      - 'Message History': 'message_history.md'
+      - 'Reactions': 'reactions.md'
+      - 'Threads': 'threads.md'
+      - 'Typing Indicator': 'typing_indicator.md'
+      - 'Webhooks': 'webhooks.md'
+    - 'Advanced Topics':
+      - 'Caching': 'caching.md'
+      - 'Sharding': 'sharding.md'
+      - 'Internationalization': 'i18n.md'
+      - 'Voice': 'voice_features.md'
+      - 'Task Loop': 'task_loop.md'
+      - 'Extension Loader': 'extension_loader.md'
+      - 'Scheduled Events': 'scheduled_events.md'
+  - 'API Reference':
+    - 'HTTP Client': 'http_client.md'
+    - 'Gateway': 'gateway.md'
+    - 'Permissions': 'permissions.md'
+    - 'Audit Logs': 'audit_logs.md'
+    - 'Commands': 'commands.md'
+    - 'Converters': 'converters.md'
+    - 'Invites': 'invites.md'
+    - 'Mentions': 'mentions.md'
+    - 'OAuth2': 'oauth2.md'
+    - 'Presence': 'presence.md'
+    - 'Voice Client': 'voice_client.md'
\ No newline at end of file