diff --git a/README.md b/README.md
index bbc9df8..e16d1d7 100644
--- a/README.md
+++ b/README.md
@@ -1,72 +1,483 @@
 # Thechart
 App to manage medication and see the evolution of its effects.
 
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Running the Application](#running-the-application)
+- [Development](#development)
+- [Deployment](#deployment)
+- [Docker Usage](#docker-usage)
+- [Troubleshooting](#troubleshooting)
+- [Make Commands Reference](#make-commands-reference)
+
+## Prerequisites
+
+Before installing Thechart, ensure you have the following installed on your system:
+
+### Required Software
+- **Python 3.13 or higher** - The application requires Python 3.13+
+- **uv** - For fast dependency management and virtual environment handling
+- **Git** - For version control (if cloning from repository)
+
+### Installing Prerequisites
+
+#### Install Python 3.13
+**Ubuntu/Debian:**
+```shell
+sudo apt update
+sudo apt install python3.13 python3.13-venv python3.13-dev
+```
+
+**macOS (using Homebrew):**
+```shell
+brew install python@3.13
+```
+
+**Windows:**
+Download and install from [python.org](https://www.python.org/downloads/)
+
+#### Install uv
+**All Platforms:**
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**macOS (using Homebrew):**
+```shell
+brew install uv
+```
+
+**Windows (using PowerShell):**
+```shell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+**Alternative (using pip):**
+```shell
+pip install uv
+```
+
+Add uv to your PATH (usually done automatically by the installer):
+```shell
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+#### Verify Installation
+```shell
+python3.13 --version
+uv --version
+```
+
 ## Installation
 
-### Install dev environment and dependencies
-The Makefile is set to use the fish shell by default, see the section on [`bash/zsh/csh`](#bash/zsh/csh). The environment will be activated as well, therefore the next section can be skiped, and you can jump to [`run the app`](#Run%20the%20app).
+### Quick Setup (Recommended)
+The Makefile is configured to use the fish shell by default. For other shells, see the [shell-specific instructions](#shell-specific-activation) below.
+
+**Note:** The current Makefile still uses Poetry commands. If you've switched to uv, you may need to update the Makefile or use the manual installation method below.
+
 ```shell
 make install
 ```
 
-### Activate the environment according to your shell
+This command will:
+- Set up the Python virtual environment using uv
+- Install all required dependencies
+- Install development dependencies
+- Set up pre-commit hooks for code quality
+- Run initial code formatting and linting
 
-#### bash/zsh/csh
+### Manual Installation
+If you prefer to set up the environment manually:
+
+1. **Clone the repository** (if not already done):
 ```shell
-eval $(poetry env activate)
+git clone <repository-url>
+cd thechart
 ```
 
-#### fish
+2. **Create and activate virtual environment:**
 ```shell
-eval (poetry env activate)
+uv venv --python 3.13
+uv sync
 ```
-or
+
+3. **Install pre-commit hooks** (for development):
+```shell
+uv run pre-commit install --install-hooks --overwrite
+uv run pre-commit autoupdate
+```
+
+### Migrating from Poetry to uv
+
+If you have an existing Poetry setup and want to migrate to uv:
+
+1. **Remove Poetry environment** (optional):
+```shell
+poetry env remove python
+```
+
+2. **Create new uv environment:**
+```shell
+uv venv --python 3.13
+uv sync
+```
+
+3. **Update your workflow:** Replace `poetry run` with `uv run` in your commands.
+
+The `pyproject.toml` file remains compatible between Poetry and uv, so no changes are needed there.
+
+### Shell-Specific Activation
+
+If the automatic environment activation doesn't work or you're using a different shell, manually activate the environment:
+
+#### fish shell (default)
+```shell
+source .venv/bin/activate.fish
+```
+or use the convenience command:
 ```shell
 make shell
 ```
 
-## Run the app
+#### bash/zsh
+```shell
+source .venv/bin/activate
+```
+
+#### PowerShell (Windows)
+```shell
+.venv\Scripts\Activate.ps1
+```
+
+#### Using uv run (recommended)
+For any command, you can use `uv run` to automatically use the virtual environment:
+```shell
+uv run python src/main.py
+uv run pre-commit run --all-files
+```
+
+## Running the Application
+
+### Quick Start
+After installation, run the application with:
 ```shell
 make run
 ```
 
-## Build container image
+### Manual Run
+Alternatively, you can run the application directly:
+```shell
+uv run python src/main.py
+```
+or if you have activated the virtual environment:
+```shell
+python src/main.py
+```
+
+### First-Time Setup
+On first run, the application will:
+- Create a default CSV data file (`thechart_data.csv`) if it doesn't exist
+- Set up logging in the `logs/` directory
+- Create necessary configuration files
+
+## Development
+
+### Code Quality Tools
+The project includes several code quality tools that are automatically set up:
+
+#### Formatting and Linting
+```shell
+make format  # Format code with ruff
+make lint    # Run linter checks
+```
+
+**With uv directly:**
+```shell
+uv run ruff format .  # Format code
+uv run ruff check .   # Check for issues
+```
+
+#### Running Tests
+```shell
+make test    # Run unit tests
+```
+
+**With uv directly:**
+```shell
+uv run pytest  # Run tests with pytest
+```
+
+### Package Management with uv
+
+#### Adding Dependencies
+```shell
+# Add a runtime dependency
+uv add package-name
+
+# Add a development dependency
+uv add --dev package-name
+
+# Add specific version
+uv add "package-name>=1.0.0"
+```
+
+#### Removing Dependencies
+```shell
+uv remove package-name
+```
+
+#### Updating Dependencies
+```shell
+# Update all dependencies
+uv sync --upgrade
+
+# Update specific package
+uv add "package-name>=new-version"
+```
+
+#### Pre-commit Hooks
+Pre-commit hooks are automatically installed and will run on every commit to ensure code quality. They include:
+- Code formatting with ruff
+- Linting checks
+- Import sorting
+- Basic file checks
+
+### Development Dependencies
+The following development tools are included:
+- **ruff** - Fast Python linter and formatter
+- **pre-commit** - Git hook management
+- **pyinstaller** - For creating standalone executables
+
+## Deployment
+
+### Creating a Standalone Executable
+
+#### Linux/Unix Deployment
+Deploy the application as a standalone executable that can run without Python installed:
+
+```shell
+make deploy
+```
+
+This command will:
+1. **Create a standalone executable** using PyInstaller
+2. **Install the executable** to `~/Applications/`
+3. **Copy data file** to `~/Documents/thechart_data.csv`
+4. **Create desktop entry** for easy access from the applications menu
+5. **Validate desktop file** to ensure proper integration
+
+#### Manual Deployment Steps
+If you prefer to deploy manually:
+
+1. **Build the executable:**
+```shell
+pyinstaller --name thechart \
+    --optimize 2 \
+    --onefile \
+    --windowed \
+    --hidden-import='PIL._tkinter_finder' \
+    --icon='chart-671.png' \
+    --add-data="./.env:." \
+    --add-data='./chart-671.png:.' \
+    --add-data='./thechart_data.csv:.' \
+    src/main.py
+```
+
+2. **Install files:**
+```shell
+# Copy executable
+cp ./dist/thechart ~/Applications/
+
+# Copy data file
+cp ./thechart_data.csv ~/Documents/
+
+# Install desktop entry (Linux)
+cp ./deploy/thechart.desktop ~/.local/share/applications/
+desktop-file-validate ~/.local/share/applications/thechart.desktop
+```
+
+#### macOS/Windows Deployment
+**Note:** macOS and Windows deployment is planned for future releases. Currently, you can run the application using Python directly on these platforms.
+
+For now, use:
+```shell
+python src/main.py
+```
+
+### Deployment Requirements
+- **PyInstaller** (included in dev dependencies)
+- **Icon file** (`chart-671.png`)
+- **Desktop file** (`deploy/thechart.desktop` for Linux)
+
+## Docker Usage
+
+## Docker Usage
+
+### Building the Container Image
+Build a multi-platform Docker image:
 ```shell
 make build
 ```
 
-## Run unit tests
+### Running with Docker Compose
+The project includes Docker Compose configuration for easy container management:
+
+1. **Start the application:**
 ```shell
-make test
+make start
 ```
 
-## Deploy the app
-### Linux / Unix
-The app will be deployed in **~/Applications**, the CSV data file *thechart_data.csv* will be store in **~/Documents**.
+2. **Stop the application:**
 ```shell
-make deploy
+make stop
 ```
-### MacOS / Windows
-TODO: use OS specific flags with *pyinstaller*.
 
-## Make options
-Show the help menu:
+3. **Access container shell:**
+```shell
+make attach
+```
+
+### Manual Docker Commands
+If you prefer using Docker directly:
+
+```shell
+# Build image
+docker build -t thechart .
+
+# Run container
+docker run -it --rm thechart
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Python Version Conflicts
+**Problem:** `uv sync` fails with Python version errors.
+**Solution:** Ensure Python 3.13+ is installed and specify the correct version:
+```shell
+uv venv --python 3.13
+uv sync
+```
+
+#### Permission Denied During Deployment
+**Problem:** Cannot copy files to `~/Applications/` or `~/Documents/`.
+**Solution:** Ensure directories exist and have proper permissions:
+```shell
+mkdir -p ~/Applications ~/Documents
+chmod 755 ~/Applications ~/Documents
+```
+
+#### Missing System Dependencies
+**Problem:** Application fails to start due to missing system libraries.
+**Solution:** Install required system packages:
+
+**Ubuntu/Debian:**
+```shell
+sudo apt install python3-tk python3-dev build-essential
+```
+
+**macOS:**
+```shell
+brew install tcl-tk
+```
+
+#### Virtual Environment Issues
+**Problem:** Environment activation fails or commands not found.
+**Solution:** Rebuild the virtual environment:
+```shell
+rm -rf .venv
+uv venv --python 3.13
+uv sync
+```
+
+### Logs and Debugging
+Application logs are stored in the `logs/` directory:
+- `app.log` - General application logs
+- `app.error.log` - Error messages
+- `app.warning.log` - Warning messages
+
+To enable debug logging, modify the logging configuration in `src/logger.py`.
+
+### Getting Help
+If you encounter issues not covered here:
+1. Check the application logs in the `logs/` directory
+2. Ensure all prerequisites are properly installed
+3. Try rebuilding the virtual environment
+4. Verify file permissions for deployment directories
+
+## Make Commands Reference
+
+The project uses a Makefile to simplify common development and deployment tasks.
+
+### Show Help Menu
 ```shell
 make help
 ```
-Sub-commands listed below:
-```
-attach               Open a shell in the container
-build                Build the Docker image
-deploy               Deploy standalone app executable
-format               Format the code
-help                 Show this help
-install              Set up the development environment
-lint                 Run the linter
-requirements         Export the requirements to a file
-run                  Run the application
-shell                Open a shell in the local environment
-start                Start the app
-stop                 Stop the app
-test                 Run the tests
+
+### Available Commands
+| Command | Description |
+|---------|-------------|
+| `install` | Set up the development environment |
+| `run` | Run the application |
+| `shell` | Open a shell in the local environment |
+| `format` | Format the code with ruff |
+| `lint` | Run the linter |
+| `test` | Run the tests |
+| `requirements` | Export the requirements to a file |
+| `build` | Build the Docker image |
+| `start` | Start the app (Docker) |
+| `stop` | Stop the app (Docker) |
+| `attach` | Open a shell in the container |
+| `deploy` | Deploy standalone app executable |
+| `help` | Show this help |
+
+### Quick Reference
+```shell
+# Development workflow
+make install    # One-time setup
+make run        # Run application
+make test       # Run tests
+make format     # Format code
+make lint       # Check code quality
+
+# Deployment
+make deploy     # Create standalone executable
+
+# Docker
+make build      # Build container image
+make start      # Start containerized app
+make stop       # Stop containerized app
 ```
+
+---
+
+## Why uv?
+
+**uv** is a fast Python package installer and resolver, written in Rust. It offers several advantages over Poetry:
+
+- **Speed**: 10-100x faster than pip and Poetry
+- **Compatibility**: Drop-in replacement for pip with Poetry-like project management
+- **Simplicity**: Unified tool for package management and virtual environments
+- **Standards**: Follows Python packaging standards (PEP 621, etc.)
+
+### Key uv Commands vs Poetry
+
+| Task | uv Command | Poetry Equivalent |
+|------|------------|-------------------|
+| Create virtual environment | `uv venv` | `poetry env use` |
+| Install dependencies | `uv sync` | `poetry install` |
+| Add package | `uv add package` | `poetry add package` |
+| Run command | `uv run command` | `poetry run command` |
+| Activate environment | `source .venv/bin/activate` | `poetry shell` |
+
+**Project Structure:**
+- `src/` - Main application source code
+- `logs/` - Application log files
+- `deploy/` - Deployment configuration files
+- `build/` - Build artifacts (created during deployment)
+- `.venv/` - Virtual environment (created by uv)
+- `uv.lock` - Lock file with exact dependency versions
+- `pyproject.toml` - Project configuration and dependencies
+- `thechart_data.csv` - Application data file