diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 753cdcf8..de21afea 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -21,6 +21,15 @@ repos:
         name: run check-hooks-apply
         description: check that all the hooks apply to the repository
 
+  - repo: https://github.com/thlorenz/doctoc.git
+    rev: 59dcae910a6ad4bbe8711275b854e3cd5c30f08b # frozen: v2.5.0
+    hooks:
+      - id: doctoc
+        name: add TOC for Markdown files
+        description: Automatically keep the README table of contents up to date
+        args: [--maxlevel, "6"]
+        files: ^README\.md$
+
   - repo: local
     hooks:
       - id: check-zip-file-is-not-committed
diff --git a/README.md b/README.md
index 3a58f994..5be6bcb5 100644
--- a/README.md
+++ b/README.md
@@ -25,15 +25,70 @@
 
 ## 📋 Table of Contents
 
-- [About the Project](#-about-the-project)
-- [How to Add Yourself](#-how-to-add-yourself)
-- [YAML File Format](#-yaml-file-format)
-- [Local Development](#-local-development-optional)
-- [Contribution Guidelines](#-contribution-guidelines)
-- [Troubleshooting](#-troubleshooting--faq)
-- [Git Workflow & Keeping in Sync](#-git-workflow--keeping-in-sync)
-- [Contributing with GitHub CLI](#-contributing-with-github-cli)
-- [License](#-license)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [🎯 About the Project](#-about-the-project)
+  - [🛠️ Tech Stack](#-tech-stack)
+  - [✨ Features](#-features)
+- [🚀 How to Add Yourself](#-how-to-add-yourself)
+  - [Step 1: Fork the Repository](#step-1-fork-the-repository)
+  - [Step 2: Clone Your Fork and Set Up Upstream](#step-2-clone-your-fork-and-set-up-upstream)
+  - [Step 3: Create a Feature Branch](#step-3-create-a-feature-branch)
+  - [Step 4: Create Your Profile File](#step-4-create-your-profile-file)
+  - [Step 5: Fill In Your Details](#step-5-fill-in-your-details)
+  - [Step 6: Test Locally (Optional but Recommended)](#step-6-test-locally-optional-but-recommended)
+  - [Step 7: Commit Your Changes](#step-7-commit-your-changes)
+  - [Step 8: Create a Pull Request](#step-8-create-a-pull-request)
+  - [Step 9: Wait for Review ⏳](#step-9-wait-for-review-)
+- [📝 YAML File Format](#-yaml-file-format)
+  - [Required Fields](#required-fields)
+  - [Optional Fields](#optional-fields)
+  - [Field Guidelines](#field-guidelines)
+  - [📚 Real Examples](#-real-examples)
+- [💻 Local Development (Optional)](#-local-development-optional)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Build Commands](#build-commands)
+  - [Quality Checks with prek](#quality-checks-with-prek)
+  - [Project Structure](#project-structure)
+- [🤝 Contribution Guidelines](#-contribution-guidelines)
+  - [Code of Conduct](#code-of-conduct)
+  - [PR Review Process](#pr-review-process)
+  - [What Gets Approved?](#what-gets-approved)
+  - [CI/CD Checks](#cicd-checks)
+- [🔧 Troubleshooting & FAQ](#-troubleshooting--faq)
+  - [Common Issues](#common-issues)
+    - [❌ Build Fails: "Invalid YAML"](#-build-fails-invalid-yaml)
+    - [❌ "GitHub username not found"](#-github-username-not-found)
+    - [❌ My profile doesn't show up](#-my-profile-doesnt-show-up)
+    - [❌ prek hooks fail](#-prek-hooks-fail)
+  - [FAQ](#faq)
+- [🔀 Git Workflow & Keeping in Sync](#-git-workflow--keeping-in-sync)
+  - [The Golden Rules](#the-golden-rules)
+  - [🛠️ Essential Git Commands for Contributors](#-essential-git-commands-for-contributors)
+    - [1. `git remote` — Manage your remote connections](#1-git-remote--manage-your-remote-connections)
+    - [2. `git fetch` — Download changes without merging](#2-git-fetch--download-changes-without-merging)
+    - [3. `git pull` — Fetch and integrate in one step](#3-git-pull--fetch-and-integrate-in-one-step)
+    - [4. `git checkout -b` — Create and switch to a feature branch](#4-git-checkout--b--create-and-switch-to-a-feature-branch)
+    - [5. `git rebase` — Replay your commits on top of the latest upstream](#5-git-rebase--replay-your-commits-on-top-of-the-latest-upstream)
+    - [6. `git stash` — Save work-in-progress without committing](#6-git-stash--save-work-in-progress-without-committing)
+    - [7. `git log` — Explore commit history](#7-git-log--explore-commit-history)
+  - [🔄 Full Day-to-Day Sync Workflow](#-full-day-to-day-sync-workflow)
+- [🖥️ Contributing with GitHub CLI](#-contributing-with-github-cli)
+  - [Step 1: Fork the Repository](#step-1-fork-the-repository-1)
+  - [Step 2: Create a Feature Branch](#step-2-create-a-feature-branch)
+  - [Step 3: Create Your Profile File](#step-3-create-your-profile-file)
+  - [Step 4: Test Locally (Optional but Recommended)](#step-4-test-locally-optional-but-recommended)
+  - [Step 5: Commit and Push](#step-5-commit-and-push)
+  - [Step 6: Open a Pull Request with `gh`](#step-6-open-a-pull-request-with-gh)
+  - [Step 7: Monitor CI and Respond to Feedback](#step-7-monitor-ci-and-respond-to-feedback)
+- [📄 License](#-license)
+  - [What this means](#what-this-means)
+- [🙏 Acknowledgments](#-acknowledgments)
+- [📞 Contact & Support](#-contact--support)
+
+<!-- END doctoc -->
 
 ---