From 44d452a82fd3360771c47e2c569415ebcb75b6c3 Mon Sep 17 00:00:00 2001
From: KoalaDev <6156589+Shik3i@users.noreply.github.com>
Date: Thu, 2 Jul 2026 22:58:19 +0200
Subject: [PATCH] docs: update and categorize all entries in docs/README.md

---
 docs/README.md | 32 +++++++++++++++++++++++++++-----
 1 file changed, 27 insertions(+), 5 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index edd0e49..47d10ab 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,8 +1,30 @@
 # Technical Documentation
 
-This directory contains deep-dives into the KoalaSync protocol and architecture.
+This directory contains deep-dives into the KoalaSync protocol, architecture, roadmap, and operational guidelines.
 
-- [HOW_IT_WORKS.md](HOW_IT_WORKS.md): Step-by-step walkthrough of every user flow, from room creation to synchronized playback. Ideal for store reviewers and manual testers.
-- [ARCHITECTURE.md](ARCHITECTURE.md): Communication flows, Dual Heartbeat, and Sync logic.
-- [SYNC_GUIDE.md](SYNC_GUIDE.md): Protocol constants and sync requirements.
-- [TRANSLATION.md](TRANSLATION.md): Translation and localization guide for the extension and website.
+## 🏗️ Core Architecture & Design
+
+- **[ARCHITECTURE.md](ARCHITECTURE.md)**: Overview of the communication flows, Dual Heartbeat architecture, and synchronization logic.
+- **[HOW_IT_WORKS.md](HOW_IT_WORKS.md)**: Step-by-step walkthrough of every user flow, from room creation to synchronized playback. Ideal for store reviewers and manual testers.
+- **[host-control-mode.md](host-control-mode.md)**: Design, requirements, and edge cases of the Host Control feature.
+
+## 📡 Protocol & Synchronization
+
+- **[PROTOCOL.md](PROTOCOL.md)**: Low-level message format and payload descriptions for the KoalaSync sync protocol.
+- **[SYNC_GUIDE.md](SYNC_GUIDE.md)**: Guide on keeping protocol constants synchronized across the workspace.
+
+## 📋 Compatibility, Roadmap & Contribution
+
+- **[TESTED_SERVICES.md](TESTED_SERVICES.md)**: Status of compatibility with major streaming services and contribution guidelines for testing new platforms.
+- **[KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md)**: Threat model and accepted design limitations (NOFIX entries) for security audits.
+- **[ROADMAP.md](ROADMAP.md)**: Planned features, backlog items, and rejected proposals.
+- **[TRANSLATION.md](TRANSLATION.md)**: Guide for native speakers to contribute and audit dynamic extension/website translations.
+
+## 🚀 DevOps & Releases
+
+- **[devops.md](devops.md)**: Guide on the automated tag-based release pipeline.
+- **[CHANGELOG.md](CHANGELOG.md)**: Detailed history of releases and changes.
+
+---
+
+*For high-level project information and developer setup instructions, refer to the root [README.md](../README.md).*