diff --git a/README.md b/README.md
index b853021..8ae6109 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,48 @@
 
 <img src="asset/BrewBar_icon.png" width="128" alt="BrewBar's logo">
 
-# Brew
+# BrewBar
 
-### A macOS menu bar app that monitors Homebrew updates and lets you upgrade packages directly from the tray.
\ No newline at end of file
+### A macOS menu bar app that monitors Homebrew updates and lets you upgrade packages directly from the tray.
+
+</div>
+
+## Features
+
+- 🔄 Periodic update checks — configurable from 30 minutes to 24 hours, or any custom interval
+- 📋 Outdated package list with versions (`wget 1.21 → 1.22`), one-click single upgrades
+- 📦 Upgrade All, with an optional confirmation dialog
+- 🤖 Optional auto-upgrade, separately configurable for formulae and casks
+- 👀 Self-updating casks (`--greedy`) included in checks, can be disabled
+- 🔔 Optional notification when new updates appear
+- 🔢 Optional outdated count next to the menu bar icon
+- 🔑 Native password dialog naming the app when an upgrade needs admin rights
+- 📜 Log window with the full brew output
+- ⚙️ Launch at login
+
+## Install
+
+```sh
+brew tap maxsoch/brewbar https://forgejo.socheleau.fr/maxsoch/BrewBar.git
+brew install --cask maxsoch/brewbar/brewbar
+xattr -dr com.apple.quarantine /Applications/BrewBar.app
+```
+
+The `xattr` line is needed because the app is not notarized — without it,
+Gatekeeper blocks the app on any Mac that didn't build it. Repeat it after
+upgrades.
+
+**Requires:** macOS 13+ (Ventura) and [Homebrew](https://brew.sh).
+
+## Build from source
+
+```sh
+git clone https://forgejo.socheleau.fr/maxsoch/BrewBar.git
+cd BrewBar
+xcodebuild -project BrewBar.xcodeproj -scheme BrewBar -configuration Release -destination "platform=macOS" build SYMROOT=build
+open build/Release/BrewBar.app
+```
+
+No dependencies — plain AppKit, no SPM/CocoaPods/Carthage.
+
+Releases are documented in [RELEASING.md](RELEASING.md).