docs: complete documentation for Milestone 4

- Rewrite README.md with overview, requirements, setup, run, tests
  sections
- Add docs/flowchart.md with Mermaid diagram and link to diagrams.net
  source
- Update docs/plan.md to mark Milestone 4 as complete

README.md

@@ -1,84 +1,94 @@
-# 🚀 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.
+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
+## 📚 Table of Contents
-
+
-- [Overview](#-overview)
+- [Overview](#-overview)
-- [Requirements](#-requirements)
+- [Requirements](#-requirements)
-- [Setup](#-setup)
+- [Setup](#-setup)
-- [Run](#-run)
+- [Run](#-run)
-- [Tests](#-tests)
+- [Tests](#-tests)
-- [License](#-license)
+- [License](#-license)
-- [Links](#-links)
+- [Links](#-links)
-
+
-## 🧭 Overview
+## 🧭 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.
+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).
+See the [program flowchart](docs/flowchart.md) and the [plan and milestones](docs/plan.md).
-
+
-## 📋 Requirements
+### 🖼️ Screenshots
-
+
-- Python 3.13 or newer
+Entering a bid:
-- No runtime dependencies
+
-- `pytest` for the tests (installed by the `dev` extra)
+![Entering a bid](docs/images/bidding.png)
-- [Doxygen](https://www.doxygen.nl/) (optional, to generate the API documentation)
+
-
+Announcing the winner:
-## 🛠️ Setup
+
-
+![Announcing the winner](docs/images/winner.png)
-Create and activate a local virtual environment, upgrade pip, then install the project with its development tools.
+
-
+## 📋 Requirements
-Windows (PowerShell):
+
-
+- Python 3.13 or newer
-```powershell
+- No runtime dependencies
-python -m venv .venv
+- `pytest` for the tests (installed by the `dev` extra)
-.venv\Scripts\Activate.ps1
+- [Doxygen](https://www.doxygen.nl/) (optional, to generate the API documentation)
-python -m pip install --upgrade pip
+
-python -m pip install -e ".[dev]"
+## 🛠️ Setup
-```
+
-
+Create and activate a local virtual environment, upgrade pip, then install the project with its development tools.
-Linux / macOS:
+
-
+Windows (PowerShell):
-```bash
+
-python3 -m venv .venv
+```powershell
-source .venv/bin/activate
+python -m venv .venv
-python -m pip install --upgrade pip
+.venv\Scripts\Activate.ps1
-python -m pip install -e ".[dev]"
+python -m pip install --upgrade pip
-```
+python -m pip install -e ".[dev]"
-
+```
-## ▶️ Run
+
-
+Linux / macOS:
-With the virtual environment active:
+
-
+```bash
-```bash
+python3 -m venv .venv
-python -m secret_auction.main
+source .venv/bin/activate
-```
+python -m pip install --upgrade pip
-
+python -m pip install -e ".[dev]"
-or use the installed command:
+```
-
+
-```bash
+## ▶️ Run
-secret-auction
+
-```
+With the virtual environment active:
-
+
-## 🧪 Tests
+```bash
-
+python -m secret_auction.main
-```bash
+```
-python -m pytest
+
-```
+or use the installed command:
-
+
-To generate the API documentation (output in `docs/doxygen/`):
+```bash
-
+secret-auction
-```bash
+```
-doxygen Doxyfile
+
-```
+## 🧪 Tests
-
+
-## 📄 License
+```bash
-
+python -m pytest
-Licensed under the GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
+```
-
+
-## 🔗 Links
+To generate the API documentation (output in `docs/doxygen/`):
-
+
-- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/009-the_secret_auction_program)
+```bash
-- [Documentation](docs/)
+doxygen Doxyfile
-- [Issue tracker](https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/009-the_secret_auction_program/issues)
+```
+
+## 📄 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)