diff --git a/README.md b/README.md
index e69de29..a602b9b 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,61 @@
+# F3 Picoclaw XMPP
+
+An XMPP chatbot bridge that connects an XMPP account to a Nanobot AI backend via WebSocket.
+
+## Features
+
+- Listens for messages in XMPP chat rooms and direct messages
+- Responds when mentioned (`@botname`) in group chats
+- Replies to all direct messages automatically
+- Streams AI responses from Nanobot WebSocket API
+- Configurable logging levels
+
+## Requirements
+
+- Python >= 3.10
+- [uv](https://docs.astral.sh/uv/) package manager
+
+## Setup
+
+```bash
+# Install dependencies
+uv sync
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your XMPP credentials and Nanobot endpoint
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `XMPP_USERNAME` | Full JID for the XMPP bot account |
+| `XMPP_PASSWORD` | XMPP account password |
+| `XMPP_ROOMS` | Comma-separated list of MUC rooms to join |
+| `NANOBOT_WS_ENDPOINT` | WebSocket URL of the Nanobot AI server |
+| `NANOBOT_WS_TOKEN` | Authentication token for the Nanobot |
+| `DEBUG` | Logging level: `debug`, `info`, `warn`, `error`, `critical` |
+
+## Usage
+
+```bash
+# Run the XMPP-to-Nanobot bridge
+uv run python -m src.server
+```
+
+## Project Structure
+
+```
+src/
+├── server.py    # Main entry point - bridges XMPP and Nanobot
+├── xmpp.py      # XMPP bot client (slixmpp)
+├── nanobot.py   # Nanobot WebSocket client
+└── log.py       # Logging configuration
+```
+
+## Tech Stack
+
+- Python 3.14 / asyncio
+- [slixmpp](https://github.com/poezio/slixmpp) for XMPP
+- [websockets](https://github.com/aaugustin/websockets) for WebSocket communication
diff --git a/src/__init__.py b/src/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/nanobot.py b/src/nanobot.py
index 41c3bd3..9edf852 100644
--- a/src/nanobot.py
+++ b/src/nanobot.py
@@ -4,7 +4,7 @@ import os
 
 import websockets
 
-from log import main_logger
+from .log import main_logger
 
 NANOBOT_WS_ENDPOINT = os.getenv("NANOBOT_WS_ENDPOINT")
 NANOBOT_WS_TOKEN = os.getenv("NANOBOT_WS_TOKEN")
diff --git a/src/server.py b/src/server.py
index 4b69414..ba9b2a0 100644
--- a/src/server.py
+++ b/src/server.py
@@ -1,9 +1,9 @@
 import asyncio
 import os
 
-from nanobot import Nanobot
-from xmpp import XmppBot
-from log import main_logger
+from .nanobot import Nanobot
+from .xmpp import XmppBot
+from .log import main_logger
 
 
 async def main():
diff --git a/src/xmpp.py b/src/xmpp.py
index 6bb0f40..1db0a64 100644
--- a/src/xmpp.py
+++ b/src/xmpp.py
@@ -1,7 +1,7 @@
 import os
 
 import slixmpp
-from log import main_logger
+from .log import main_logger
 
 
 class XmppBot(slixmpp.ClientXMPP):