diff --git a/README.md b/README.md
index be5bc61..caf1d3d 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,94 @@
-# 009-the_secret_auction_program
-
+# 🚀 Secret Auction Program
+
+A beginner-friendly Python program that runs a blind auction: bidders enter their name and bid one after another, the screen is cleared between bidders, and the highest bidder wins.
+
+## 📚 Table of Contents
+
+- [Overview](#-overview)
+- [Requirements](#-requirements)
+- [Setup](#-setup)
+- [Run](#-run)
+- [Tests](#-tests)
+- [License](#-license)
+- [Links](#-links)
+
+## 🧭 Overview
+
+This is the Day 9 project of Udemy's *100 Days of Code: The Complete Python Pro Bootcamp*. Each bidder enters a name and a bid, which are stored in a dictionary (name → bid). After each bidder the program asks whether there are more bidders and, if so, clears the screen so the next bidder cannot see earlier bids. When everyone has bid, the program announces the winner.
+
+See the [program flowchart](docs/flowchart.md) and the [plan and milestones](docs/plan.md).
+
+### 🖼️ Screenshots
+
+Entering a bid:
+
+![Entering a bid](docs/images/bidding.png)
+
+Announcing the winner:
+
+![Announcing the winner](docs/images/winner.png)
+
+## 📋 Requirements
+
+- Python 3.13 or newer
+- No runtime dependencies
+- `pytest` for the tests (installed by the `dev` extra)
+- [Doxygen](https://www.doxygen.nl/) (optional, to generate the API documentation)
+
+## 🛠️ Setup
+
+Create and activate a local virtual environment, upgrade pip, then install the project with its development tools.
+
+Windows (PowerShell):
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Linux / macOS:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## ▶️ Run
+
+With the virtual environment active:
+
+```bash
+python -m secret_auction.main
+```
+
+or use the installed command:
+
+```bash
+secret-auction
+```
+
+## 🧪 Tests
+
+```bash
+python -m pytest
+```
+
+To generate the API documentation (output in `docs/doxygen/`):
+
+```bash
+doxygen Doxyfile
+```
+
+## 📄 License
+
+Licensed under the GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
+
+## 🔗 Links
+
+- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/009-the_secret_auction_program)
+- [Documentation](docs/)
+- [Issue tracker](https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/009-the_secret_auction_program/issues)
diff --git a/docs/flowchart.md b/docs/flowchart.md
new file mode 100644
index 0000000..19d083a
--- /dev/null
+++ b/docs/flowchart.md
@@ -0,0 +1,17 @@
+# Blind Auction Flowchart
+
+Original chart: [diagrams.net](https://viewer.diagrams.net/?highlight=0000ff&edit=_blank&layers=1&nav=1&title=Blind%20Auction%20Flow%20Chart)
+
+```mermaid
+flowchart TD
+    A([Start]) --> B[Print welcome message]
+    B --> C[bids = empty dictionary]
+    C --> D[/Ask name/]
+    D --> E[/Ask bid, repeat until valid/]
+    E --> F[Store bids name = bid]
+    F --> G{Other bidders?}
+    G -- yes --> H[Clear screen] --> D
+    G -- no --> I[Find highest bid]
+    I --> J[/Print winner/]
+    J --> K([End])
+```
diff --git a/docs/images/bidding.png b/docs/images/bidding.png
new file mode 100644
index 0000000..7d5ce34
Binary files /dev/null and b/docs/images/bidding.png differ
diff --git a/docs/images/winner.png b/docs/images/winner.png
new file mode 100644
index 0000000..cfbc5ec
Binary files /dev/null and b/docs/images/winner.png differ
diff --git a/docs/plan.md b/docs/plan.md
index db193ee..c17d3c1 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -34,7 +34,7 @@ Work on ONE milestone at a time. Each milestone is one branch (`milestone/NN-nam
 
 ## Milestone 4 - Documentation (`milestone/04-docs`)
 
-- [ ] `README.md` from the template (Overview, Requirements, Setup incl. creating/activating `.venv` and `python -m pip install --upgrade pip`, Run, Tests, License AGPL, Links)
-- [ ] `docs/flowchart.md` (Mermaid plus link to the diagrams.net chart)
-- [ ] Generate Doxygen docs if `doxygen` is installed
+- [x] `README.md` from the template (Overview, Requirements, Setup incl. creating/activating `.venv` and `python -m pip install --upgrade pip`, Run, Tests, License AGPL, Links)
+- [x] `docs/flowchart.md` (Mermaid plus link to the diagrams.net chart)
+- [x] Generate Doxygen docs if `doxygen` is installed
 - Verify: README commands work verbatim; `.env` stays untracked