diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e59955d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,235 @@
+
+
+
+ Modern, transparent and intelligent utility for CPU management on Linux.
+
+
+
+
+## What is Superfreq
+
+Superfreq is a modern CPU frequency and power management utility for Linux
+systems. It provides intelligent control of CPU governors, frequencies, and
+power-saving features, helping optimize both performance and battery life.
+
+It is greatly inspired by auto_cpufreq, but rewritten from ground up to provide
+a smoother experience with a more efficient and more correct codebase. Some
+features are omitted, and it is _not_ a drop-in replacement for auto_cpufreq,
+but most common usecases are already implemented.
+
+## Features
+
+- **Real-time CPU Management**: Monitor and control CPU governors, frequencies,
+ and turbo boost
+- **Intelligent Power Management**: Different profiles for AC and battery
+ operation
+- **Fine-tuned Controls**: Adjust energy performance preferences, biases, and
+ frequency limits
+- **Per-core Control**: Apply settings globally or to specific CPU cores
+- **Battery Management**: Monitor battery status and power consumption
+- **System Load Tracking**: Track system load and make intelligent decisions
+- **Daemon Mode**: Run in background with adaptive polling to minimize overhead
+- **Conflict Detection**: Identifies and warns about conflicts with other power
+ management tools
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Show current system information
+superfreq info
+
+# Run as a daemon in the background
+sudo superfreq daemon
+
+# Run with verbose logging
+sudo superfreq daemon --verbose
+
+# Display comprehensive debug information
+superfreq debug
+```
+
+### CPU Governor Control
+
+```bash
+# Set CPU governor for all cores
+sudo superfreq set-governor performance
+
+# Set CPU governor for a specific core
+sudo superfreq set-governor powersave --core-id 0
+
+# Force a specific governor mode persistently
+sudo superfreq force-governor performance
+```
+
+### Turbo Boost Management
+
+```bash
+# Always enable turbo boost
+sudo superfreq set-turbo always
+
+# Disable turbo boost
+sudo superfreq set-turbo never
+
+# Let Superfreq manage turbo boost based on conditions
+sudo superfreq set-turbo auto
+```
+
+### Power and Performance Settings
+
+```bash
+# Set Energy Performance Preference (EPP)
+sudo superfreq set-epp performance
+
+# Set Energy Performance Bias (EPB)
+sudo superfreq set-epb 4
+
+# Set ACPI platform profile
+sudo superfreq set-platform-profile balanced
+```
+
+### Frequency Control
+
+```bash
+# Set minimum CPU frequency (in MHz)
+sudo superfreq set-min-freq 800
+
+# Set maximum CPU frequency (in MHz)
+sudo superfreq set-max-freq 3000
+
+# Set per-core frequency limits
+sudo superfreq set-min-freq 1200 --core-id 0
+sudo superfreq set-max-freq 2800 --core-id 1
+```
+
+## Configuration
+
+Superfreq uses TOML configuration files. Default locations:
+
+- `/etc/superfreq/config.toml`
+- `/etc/superfreq.toml`
+
+You can also specify a custom path by setting the `SUPERFREQ_CONFIG` environment
+variable.
+
+### Sample Configuration
+
+```toml
+# Settings for when connected to a power source
+[charger]
+# CPU governor to use
+governor = "performance"
+# Turbo boost setting: "always", "auto", or "never"
+turbo = "auto"
+# Energy Performance Preference
+epp = "performance"
+# Energy Performance Bias (0-15 scale or named value)
+epb = "balance_performance"
+# Platform profile (if supported)
+platform_profile = "performance"
+# Min/max frequency in MHz (optional)
+min_freq_mhz = 800
+max_freq_mhz = 3500
+
+# Settings for when on battery power
+[battery]
+governor = "powersave"
+turbo = "auto"
+epp = "power"
+epb = "balance_power"
+platform_profile = "low-power"
+min_freq_mhz = 800
+max_freq_mhz = 2500
+
+# Daemon configuration
+[daemon]
+# Base polling interval in seconds
+poll_interval_sec = 5
+# Enable adaptive polling that changes with system state
+adaptive_interval = true
+# Minimum polling interval for adaptive polling (seconds)
+min_poll_interval_sec = 1
+# Maximum polling interval for adaptive polling (seconds)
+max_poll_interval_sec = 30
+# Double the polling interval when on battery to save power
+throttle_on_battery = true
+# Logging level: Error, Warning, Info, Debug
+log_level = "Info"
+# Optional stats file path
+stats_file_path = "/var/run/superfreq-stats"
+
+# Optional: List of power supplies to ignore
+[power_supply_ignore_list]
+mouse_battery = "hid-12:34:56:78:90:ab-battery"
+# Add other devices to ignore here
+```
+
+## Advanced Features
+
+Those are the more advanced features of Superfreq that some users might be more
+inclined to use than others. If you have a use-case that is not covered, please
+create an issue.
+
+### Adaptive Polling
+
+The daemon mode uses adaptive polling to balance responsiveness with efficiency:
+
+- Increases polling frequency during system changes
+- Decreases polling frequency during stable periods
+- Reduces polling when on battery to save power
+
+### Power Supply Filtering
+
+Configure Superfreq to ignore certain power supplies (like peripheral batteries)
+that might interfere with power state detection.
+
+## Troubleshooting
+
+### Permission Issues
+
+Most CPU management commands require root privileges. If you see permission
+errors, try running with `sudo`.
+
+### Feature Compatibility
+
+Not all features are available on all hardware:
+
+- Turbo boost control requires CPU support for Intel/AMD boost features
+- EPP/EPB settings require CPU driver support
+- Platform profiles require ACPI platform profile support in your hardware
+
+### Common Problems
+
+1. **Settings not applying**: Check for conflicts with other power management
+ tools
+2. **CPU frequencies fluctuating**: May be due to thermal throttling
+3. **Missing CPU information**: Verify kernel module support for your CPU
+
+While reporting issues, please attach the results from `superfreq debug`.
+
+## Contributing
+
+Contributions to Superfreq are always welcome! Whether it's bug reports, feature
+requests, or code contributions, please feel free to contribute.
+
+If you are looking to reimplement features from auto_cpufreq, please consider
+opening an issue first and let us know what you have in mind. Certain features
+(such as the system tray) are deliberately ignored, and might not be desired in
+the codebase as they stand.
+
+### Setup
+
+You will need Cargo and Rust installed on your system. For Nix users, using
+Direnv is encouraged.
+
+Non-Nix users may get the appropriate Cargo andn Rust versions from their
+package manager.