From 253f56399da99082dda04bdd6298f2692ca9d4cb Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Mon, 2 Feb 2026 15:58:34 -0500
Subject: [PATCH] docs: restructure documentation into audience-based portals

BREAKING CHANGE: Documentation URLs have changed

New structure:
- user/ - End-user documentation (device setup, sync guides, frontend)
- developer/ - Developer documentation (API reference, protocols, specs)
- operations/ - Operations documentation (deployment, troubleshooting)
- contributing/ - Contribution guides

Changes:
- Created portal INDEX.md files for each audience section
- Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md)
- Moved API docs to developer/ (api-reference.md, collections-api.md)
- Moved sync guide to user/sync-guide.md
- Moved troubleshooting to operations/troubleshooting.md
- Moved all split API docs to developer/api/
- Renamed protocol files (kobo-protocol.md, koreader-protocol.md)
- Added placeholder user guides (frontend, user-areas, settings, admin)
- Updated all internal links to new paths
- Updated Go code (http_handler.go, navigation.go) for new paths
- Updated main INDEX.md for audience-based navigation

Benefits:
- Clear separation of user and developer documentation
- Scalable structure for future user guide expansion
- Better organization and discoverability
- Audience-specific landing pages

Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
---
 docs/INDEX.md                                 | 274 ++++++------------
 docs/contributing/INDEX.md                    |  35 +++
 docs/developer/INDEX.md                       |  77 +++++
 .../api-reference.md}                         |   0
 docs/{ => developer}/api/INDEX.md             |   4 +-
 .../api/analytics/get_analytics.md            |   0
 .../api/authentication/login.md               |   0
 .../api/authentication/logout.md              |   0
 .../api/authentication/refresh_token.md       |   0
 .../api/authentication/register.md            |   0
 .../api/book-matching/link_book.md            |   0
 .../api/book-matching/search_books.md         |   0
 docs/{ => developer}/api/collections/INDEX.md |   6 +-
 .../api/collections/add_auto_assign_rule.md   |   0
 .../api/collections/bulk_assign.md            |   0
 .../api/collections/create_collection.md      |   0
 .../api/collections/create_shelf_mapping.md   |   0
 .../api/collections/delete_collection.md      |   0
 .../api/collections/delete_shelf_mapping.md   |   0
 .../api/collections/get_collection.md         |   0
 .../api/collections/list_collections.md       |   0
 .../collections/remove_auto_assign_rule.md    |   0
 .../api/collections/test_rule.md              |   0
 .../api/collections/update_collection.md      |   0
 .../api/devices/get_devices.md                |   0
 .../api/devices/list_devices.md               |   0
 .../api/devices/register_device.md            |   0
 .../api/devices/revoke_device.md              |   0
 .../api/highlights/create_highlight.md        |   0
 .../api/highlights/delete_highlight.md        |   0
 .../api/highlights/get_highlights.md          |   0
 .../api/highlights/update_highlight.md        |   0
 .../api/libraries/add_library_folder.md       |   0
 .../api/libraries/create_library.md           |   0
 .../api/libraries/get_library.md              |   0
 .../api/libraries/get_visible_libraries.md    |   0
 .../api/libraries/set_library_visibility.md   |   0
 .../api/media-items/delete_media_item.md      |   0
 .../media-items/filter_sort_media_items.md    |   0
 .../api/media-items/get_media_item.md         |   0
 .../api/media-items/list_media_items.md       |   0
 .../api/media-items/search_media_items.md     |   0
 .../api/media-items/update_media_item.md      |   0
 docs/{ => developer}/api/notes/create_note.md |   0
 docs/{ => developer}/api/notes/delete_note.md |   0
 docs/{ => developer}/api/notes/get_notes.md   |   0
 docs/{ => developer}/api/notes/update_note.md |   0
 docs/{ => developer}/api/opds/acquisition.md  |   0
 docs/{ => developer}/api/opds/feeds.md        |   0
 docs/{ => developer}/api/opds/publication.md  |   0
 .../api/progress/delete_progress.md           |   0
 .../api/progress/get_progress.md              |   0
 .../api/progress/update_progress.md           |   0
 .../api/ratings/create_rating.md              |   0
 .../api/ratings/get_ratings.md                |   0
 .../api/sync/kobo-protocol.md}                |   0
 .../api/sync/koreader-protocol.md}            |   0
 .../api/users/change_password.md              |   0
 docs/{ => developer}/api/users/get_profile.md |   0
 .../api/users/update_profile.md               |   0
 .../{ => developer}/api/users/update_theme.md |   0
 .../{ => developer}/api/websocket/protocol.md |   0
 .../collections-api.md}                       |   0
 .../websocket-api.md}                         |   0
 docs/operations/INDEX.md                      |  34 +++
 .../troubleshooting.md}                       |   0
 docs/user/INDEX.md                            |  52 ++++
 docs/user/admin-guide.md                      |  15 +
 .../devices/kobo-setup.md}                    |   6 +-
 .../devices/koreader-setup.md}                |   4 +-
 docs/user/frontend-guide.md                   |  15 +
 docs/user/settings-guide.md                   |  14 +
 .../sync-guide.md}                            |   4 +-
 docs/user/user-areas.md                       |  14 +
 internal/docs/http_handler.go                 |   3 +-
 internal/docs/navigation.go                   |  22 +-
 76 files changed, 372 insertions(+), 207 deletions(-)
 create mode 100644 docs/contributing/INDEX.md
 create mode 100644 docs/developer/INDEX.md
 rename docs/{API_REFERENCE.md => developer/api-reference.md} (100%)
 rename docs/{ => developer}/api/INDEX.md (91%)
 rename docs/{ => developer}/api/analytics/get_analytics.md (100%)
 rename docs/{ => developer}/api/authentication/login.md (100%)
 rename docs/{ => developer}/api/authentication/logout.md (100%)
 rename docs/{ => developer}/api/authentication/refresh_token.md (100%)
 rename docs/{ => developer}/api/authentication/register.md (100%)
 rename docs/{ => developer}/api/book-matching/link_book.md (100%)
 rename docs/{ => developer}/api/book-matching/search_books.md (100%)
 rename docs/{ => developer}/api/collections/INDEX.md (84%)
 rename docs/{ => developer}/api/collections/add_auto_assign_rule.md (100%)
 rename docs/{ => developer}/api/collections/bulk_assign.md (100%)
 rename docs/{ => developer}/api/collections/create_collection.md (100%)
 rename docs/{ => developer}/api/collections/create_shelf_mapping.md (100%)
 rename docs/{ => developer}/api/collections/delete_collection.md (100%)
 rename docs/{ => developer}/api/collections/delete_shelf_mapping.md (100%)
 rename docs/{ => developer}/api/collections/get_collection.md (100%)
 rename docs/{ => developer}/api/collections/list_collections.md (100%)
 rename docs/{ => developer}/api/collections/remove_auto_assign_rule.md (100%)
 rename docs/{ => developer}/api/collections/test_rule.md (100%)
 rename docs/{ => developer}/api/collections/update_collection.md (100%)
 rename docs/{ => developer}/api/devices/get_devices.md (100%)
 rename docs/{ => developer}/api/devices/list_devices.md (100%)
 rename docs/{ => developer}/api/devices/register_device.md (100%)
 rename docs/{ => developer}/api/devices/revoke_device.md (100%)
 rename docs/{ => developer}/api/highlights/create_highlight.md (100%)
 rename docs/{ => developer}/api/highlights/delete_highlight.md (100%)
 rename docs/{ => developer}/api/highlights/get_highlights.md (100%)
 rename docs/{ => developer}/api/highlights/update_highlight.md (100%)
 rename docs/{ => developer}/api/libraries/add_library_folder.md (100%)
 rename docs/{ => developer}/api/libraries/create_library.md (100%)
 rename docs/{ => developer}/api/libraries/get_library.md (100%)
 rename docs/{ => developer}/api/libraries/get_visible_libraries.md (100%)
 rename docs/{ => developer}/api/libraries/set_library_visibility.md (100%)
 rename docs/{ => developer}/api/media-items/delete_media_item.md (100%)
 rename docs/{ => developer}/api/media-items/filter_sort_media_items.md (100%)
 rename docs/{ => developer}/api/media-items/get_media_item.md (100%)
 rename docs/{ => developer}/api/media-items/list_media_items.md (100%)
 rename docs/{ => developer}/api/media-items/search_media_items.md (100%)
 rename docs/{ => developer}/api/media-items/update_media_item.md (100%)
 rename docs/{ => developer}/api/notes/create_note.md (100%)
 rename docs/{ => developer}/api/notes/delete_note.md (100%)
 rename docs/{ => developer}/api/notes/get_notes.md (100%)
 rename docs/{ => developer}/api/notes/update_note.md (100%)
 rename docs/{ => developer}/api/opds/acquisition.md (100%)
 rename docs/{ => developer}/api/opds/feeds.md (100%)
 rename docs/{ => developer}/api/opds/publication.md (100%)
 rename docs/{ => developer}/api/progress/delete_progress.md (100%)
 rename docs/{ => developer}/api/progress/get_progress.md (100%)
 rename docs/{ => developer}/api/progress/update_progress.md (100%)
 rename docs/{ => developer}/api/ratings/create_rating.md (100%)
 rename docs/{ => developer}/api/ratings/get_ratings.md (100%)
 rename docs/{api/sync/kobo_protocol.md => developer/api/sync/kobo-protocol.md} (100%)
 rename docs/{api/sync/koreader_protocol.md => developer/api/sync/koreader-protocol.md} (100%)
 rename docs/{ => developer}/api/users/change_password.md (100%)
 rename docs/{ => developer}/api/users/get_profile.md (100%)
 rename docs/{ => developer}/api/users/update_profile.md (100%)
 rename docs/{ => developer}/api/users/update_theme.md (100%)
 rename docs/{ => developer}/api/websocket/protocol.md (100%)
 rename docs/{COLLECTIONS_API.md => developer/collections-api.md} (100%)
 rename docs/{api/WEBSOCKET_API.md => developer/websocket-api.md} (100%)
 create mode 100644 docs/operations/INDEX.md
 rename docs/{TROUBLESHOOTING.md => operations/troubleshooting.md} (100%)
 create mode 100644 docs/user/INDEX.md
 create mode 100644 docs/user/admin-guide.md
 rename docs/{devices/KOBO_SETUP.md => user/devices/kobo-setup.md} (99%)
 rename docs/{devices/KOREADER_SETUP.md => user/devices/koreader-setup.md} (99%)
 create mode 100644 docs/user/frontend-guide.md
 create mode 100644 docs/user/settings-guide.md
 rename docs/{SYNC_USER_GUIDE.md => user/sync-guide.md} (99%)
 create mode 100644 docs/user/user-areas.md

diff --git a/docs/INDEX.md b/docs/INDEX.md
index eb327a7..6ca5b8f 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -1,229 +1,137 @@
-# Bookhoard Documentation Index
+# Bookhoard Documentation
 
 Complete guide to Bookhoard documentation. Find what you need quickly.
 
 ---
 
-## 🚀 Quick Links
+## 🚀 By Audience
 
-### For New Users
-1. [README.md](../README.md) - **Start here!** Project overview and quick start
-2. [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Understanding and using sync
-3. [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) - Kobo e-reader setup
-4. [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md) - KOReader setup
+### 👤 For End Users
 
-### For Self-Hosting
-1. [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Deployment and troubleshooting
-2. [.env.example](../.env.example) - Secrets configuration (JWT and DB password)
+**[User Documentation Portal](user/INDEX.md)** - Guides for using Bookhoard features
 
-### For Contributors
-1. [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Development workflow and architecture
-2. [docs/API_REFERENCE.md](API_REFERENCE.md) - Complete API documentation
-3. [docs/COLLECTIONS_API.md](COLLECTIONS_API.md) - Collections API
-4. [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md) - WebSocket protocol
+- **Device Setup**
+  - [Kobo Setup Guide](user/devices/kobo-setup.md) - Complete Kobo e-reader configuration
+  - [KOReader Setup Guide](user/devices/koreader-setup.md) - KOReader on Kindle/Kobo/PocketBook
+
+- **Sync Configuration**
+  - [Universal Sync Guide](user/sync-guide.md) - Understanding sync, book matching, conflicts
+
+- **Frontend & Settings** (Coming Soon)
+  - Frontend Guide
+  - User Areas Guide
+  - Settings Guide
+  - Admin Guide
+
+### 👨‍💻 For Developers
+
+**[Developer Documentation Portal](developer/INDEX.md)** - Technical documentation & API reference
+
+- **API Documentation**
+  - [Complete API Reference](developer/api-reference.md) - Monolithic REST API reference (1,300+ lines)
+  - [Split Endpoint Docs](developer/api/INDEX.md) - Individual endpoints with interactive API Explorer
+  - [Collections API](developer/collections-api.md) - Collections management API
+
+- **Protocol Specifications**
+  - [Kobo Sync Protocol](developer/api/sync/kobo-protocol.md) - Kobo device sync
+  - [KOReader Sync Protocol](developer/api/sync/koreader-protocol.md) - KOReader sync
+  - [WebSocket API](developer/websocket-api.md) - Real-time events
+
+### 🔧 For Operations
+
+**[Operations Documentation Portal](operations/INDEX.md)** - Deployment & maintenance
+
+- **Deployment**
+  - [Troubleshooting Guide](operations/troubleshooting.md) - Common deployment issues and solutions
+
+- **Maintenance** (Coming Soon)
+  - Deployment Guide
+  - Maintenance Guide
+  - Monitoring Guide
+
+### 🤝 For Contributors
+
+**[Contributing Portal](contributing/INDEX.md)** - Development workflow
+
+- [Development Guide](contributing/DEVELOPMENT.md) - Architecture, setup, testing
+- [PROJECT_GUIDELINES.md](PROJECT_GUIDELINES.md) - Development rules and standards
 
 ---
 
-## 📚 Documentation by Topic
+## 📚 Quick Links
 
-### Getting Started
-- **[README.md](../README.md)** - Project overview, features, quick start guide
-- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development environment setup
-
-### Deployment & Operations
-- **[docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common deployment issues and solutions
-- **[.env.example](../.env.example)** - Required secrets (JWT_SECRET, DBPASS)
-- **[docker-compose.yml](../docker-compose.yml)** - Operational configuration with defaults
-- **[Makefile](../Makefile)** - Build and test commands
-
-### Using Sync Features
-- **[docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)** - Universal sync user guide
-  - Understanding sync
-  - Book matching and auto-linking
-  - Conflict resolution
-  - Best practices
-
-### Device Setup
-- **[docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md)** - Kobo e-reader configuration
-  - Device registration
-  - Sync configuration
-  - OPDS wireless book delivery
-  - Troubleshooting
-
-- **[docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)** - KOReader configuration
-  - Installation on Kindle/Kobo/PocketBook
-  - Sync setup
-  - OPDS catalog access
-  - Troubleshooting
-
-### API Documentation
-- **[docs/API_REFERENCE.md](API_REFERENCE.md)** - Complete REST API reference
-  - Authentication
-  - User management
-  - Libraries
-  - Media items
-  - Reading progress
-  - Notes & highlights
-  - Analytics
-  - Book matching
-  - OPDS
-  - Sync protocols (KOReader, Kobo)
-  - WebSocket
-
-- **[docs/COLLECTIONS_API.md](COLLECTIONS_API.md)** - Collections API
-  - Create and manage collections
-  - Auto-assign rules
-  - Test rules
-  - Bulk operations
-  - Device shelf mappings
-
-- **[docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md)** - WebSocket protocol
-  - Connection flow
-  - Message format
-  - Real-time sync broadcasts
-  - Authentication
-
-### Contributing
-- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development guide
-  - Architecture overview
-  - Directory structure
-  - Local development setup
-  - Testing guidelines
-  - Code style
-  - Deployment
-
-- **[PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md)** - Development rules and standards
-  - Critical prohibitions
-  - Mandatory requirements
-  - Error recovery protocol
-
-### Reference
-- **[go.mod](../go.mod)** - Go dependencies
-- **[database/schema/schema.sql](../database/schema/schema.sql)** - Database schema
-- **[bruno/](../bruno/)** - API test collections
-
----
-
-## 📖 Reading Path by Role
-
-### Self-Hoster / End User
-**Goal**: Set up and use Bookhoard for reading
-
-1. Start with [README.md](../README.md) - Understand what Bookhoard is
-2. Follow quick start in README.md to get running
-3. Set up your device:
-   - Kobo: [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md)
-   - KOReader: [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
-4. Learn about sync: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
-5. If issues arise: [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)
-
-
-
-### Developer
-**Goal**: Contribute to Bookhoard or integrate with it
-
-1. Start with [README.md](../README.md) - Project overview
-2. Read [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Architecture and setup
-3. Review [docs/API_REFERENCE.md](API_REFERENCE.md) - API endpoints
-4. Check [PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) - Development rules
-5. Explore codebase and contribute!
-
-### API Integrator
-**Goal**: Build integration with Bookhoard
-
-1. Review [README.md](../README.md) - Feature overview
-2. Study [docs/API_REFERENCE.md](API_REFERENCE.md) - All endpoints
-3. Check specialized docs:
-   - Collections: [docs/COLLECTIONS_API.md](COLLECTIONS_API.md)
-   - WebSocket: [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md)
-   - Sync: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
-4. Test with [bruno/](../bruno/) collections
+| Want to... | Go to |
+|------------|-------|
+| **Get started** | [README.md](../README.md) - Project overview and quick start |
+| **Set up a device** | [User Portal → Device Setup](user/INDEX.md) |
+| **Use the API** | [Developer Portal → API Docs](developer/INDEX.md) |
+| **Deploy Bookhoard** | [Operations Portal → Troubleshooting](operations/troubleshooting.md) |
+| **Contribute code** | [Contributing Portal → Development Guide](contributing/DEVELOPMENT.md) |
+| **Understand sync** | [User Portal → Sync Guide](user/sync-guide.md) |
 
 ---
 
 ## 🔍 Quick Find
 
 ### "How do I..."
-| ...do this? | See this document |
-|-------------|------------------|
+
+| Question | Answer |
+|----------|--------|
 | ...install Bookhoard? | [README.md](../README.md) - Quick Start |
-| ...set up my Kobo? | [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) |
-| ...set up KOReader? | [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md) |
-| ...understand sync? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) |
-| ...resolve conflicts? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Managing Conflicts |
-| ...match books? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Book Matching |
-| ...troubleshoot deployment? | [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
-| ...use the API? | [docs/API_REFERENCE.md](API_REFERENCE.md) |
-| ...set up development? | [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) |
-| ...contribute code? | [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Contributing |
+| ...set up my Kobo? | [Kobo Setup Guide](user/devices/kobo-setup.md) |
+| ...set up KOReader? | [KOReader Setup Guide](user/devices/koreader-setup.md) |
+| ...understand sync? | [Sync Guide](user/sync-guide.md) |
+| ...resolve conflicts? | [Sync Guide](user/sync-guide.md) - Managing Conflicts |
+| ...troubleshoot deployment? | [Troubleshooting Guide](operations/troubleshooting.md) |
+| ...use the API? | [API Reference](developer/api-reference.md) |
+| ...contribute code? | [Development Guide](contributing/DEVELOPMENT.md) |
 
 ### "Where is..."
-| ...this information? | See this document |
-|-------------------|------------------|
+
+| Information | Location |
+|-------------|----------|
 | ...features list? | [README.md](../README.md) |
 | ...database schema? | [database/schema/schema.sql](../database/schema/schema.sql) |
-| ...API endpoints? | [docs/API_REFERENCE.md](API_REFERENCE.md) |
+| ...API endpoints? | [API Reference](developer/api-reference.md) |
 | ...secrets config? | [.env.example](../.env.example) |
 | ...operational config? | [docker-compose.yml](../docker-compose.yml) |
-| ...deployment issues? | [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
+| ...deployment issues? | [Troubleshooting Guide](operations/troubleshooting.md) |
 
 ---
 
-## 📊 Documentation Statistics
-
-| File | Lines | Purpose | Audience |
-|------|-------|---------|----------|
-| README.md | 150 | Overview & quick start | Everyone |
-| contributing/DEVELOPMENT.md | 450 | Development workflow | Contributors |
-| API_REFERENCE.md | 1,300+ | Complete REST API | Developers, integrators |
-| COLLECTIONS_API.md | 494 | Collections API | Developers, integrators |
-| SYNC_USER_GUIDE.md | 350+ | Sync usage guide | End users |
-| TROUBLESHOOTING.md | 300 | Deployment troubleshooting | Self-hosters |
-| KOBO_SETUP.md | 598 | Kobo setup | Kobo users |
-| KOREADER_SETUP.md | 504 | KOReader setup | KOReader users |
-| WEBSOCKET_API.md | 676 | WebSocket protocol | Developers |
-| PROJECT_GUIDELINES.md | 250 | Development rules | Developers |
-
-**Total**: ~5,000 lines of comprehensive documentation
-
----
-
-## 🎯 Common Tasks
+## 🎯 Common Workflows
 
 ### Set up a new device
-1. Device setup guide: [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) or [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
-2. Sync overview: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
-3. Troubleshooting: Device-specific setup guides
-
-### Troubleshoot sync issues
-1. Check [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - "Managing Conflicts" and "Best Practices"
-2. Review device-specific guide for common issues
-3. Check [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for general issues
+1. Choose your device: [Kobo](user/devices/kobo-setup.md) or [KOReader](user/devices/koreader-setup.md)
+2. Understand sync: [Sync Guide](user/sync-guide.md)
+3. Troubleshoot: Device-specific guides
 
 ### Integrate with Bookhoard API
-1. Start with [docs/API_REFERENCE.md](API_REFERENCE.md) - Complete API reference
-2. Check [docs/COLLECTIONS_API.md](COLLECTIONS_API.md) for collections
-3. Review [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md) for real-time updates
-4. Use [bruno/](../bruno/) test collections as examples
+1. Start with [API Reference](developer/api-reference.md)
+2. Explore [Collections API](developer/collections-api.md)
+3. Review [WebSocket API](developer/websocket-api.md)
+4. Test with [bruno/](../bruno/) collections
 
 ### Deploy to production
 1. Follow [README.md](../README.md) quick start
 2. Configure environment: [.env.example](../.env.example)
-3. Review [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
-4. Check [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) for performance tuning
+3. Review [Troubleshooting Guide](operations/troubleshooting.md)
+4. Check [Development Guide](contributing/DEVELOPMENT.md) for performance tuning
 
 ---
 
 ## 📝 Contributing to Documentation
 
 When adding new features:
-1. Update [README.md](../README.md) - Add to features list if user-facing
-2. Update [docs/API_REFERENCE.md](API_REFERENCE.md) - Document new endpoints
-3. Add/update tests in [bruno/](../bruno/)
-4. Update relevant guides (SYNC_USER_GUIDE.md, device guides, etc.)
-5. Keep [PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) in mind
+
+1. **User-facing features** → Update relevant User docs
+2. **API endpoints** → Update [API Reference](developer/api-reference.md) & split docs
+3. **Backend changes** → Update [Development Guide](contributing/DEVELOPMENT.md)
+4. **Deployment changes** → Update [Operations Portal](operations/INDEX.md)
+
+Keep [PROJECT_GUIDELINES.md](PROJECT_GUIDELINES.md) in mind for documentation standards.
 
 ---
 
-**Last Updated**: 2026-02-01  
+**Last Updated**: 2026-02-02
 **Bookhoard Version**: 1.0
diff --git a/docs/contributing/INDEX.md b/docs/contributing/INDEX.md
new file mode 100644
index 0000000..45b8c31
--- /dev/null
+++ b/docs/contributing/INDEX.md
@@ -0,0 +1,35 @@
+# Contributing to Bookhoard
+
+Welcome to the Bookhoard contributing documentation. This section contains guides for contributing to the Bookhoard project.
+
+## 🚀 Getting Started
+
+- **[Development Guide](DEVELOPMENT.md)** - Development workflow and architecture
+  - Architecture overview
+  - Directory structure
+  - Local development setup
+  - Testing guidelines
+  - Code style
+  - Deployment
+
+## 📋 Project Guidelines
+
+- **[PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md)** - Development rules and standards
+  - Critical prohibitions
+  - Mandatory requirements
+  - Error recovery protocol
+  - Workflow checklists
+
+## 🤝 How to Contribute
+
+We welcome contributions! Please see our [Development Guide](DEVELOPMENT.md) for information on:
+- Setting up your development environment
+- Understanding the codebase
+- Making pull requests
+- Code review process
+- Testing requirements
+
+---
+
+**Looking for user documentation?** See the [User Portal](../user/INDEX.md)
+**Need API docs?** See the [Developer Portal](../developer/INDEX.md)
diff --git a/docs/developer/INDEX.md b/docs/developer/INDEX.md
new file mode 100644
index 0000000..b30a5df
--- /dev/null
+++ b/docs/developer/INDEX.md
@@ -0,0 +1,77 @@
+# Developer Documentation
+
+Welcome to the Bookhoard developer documentation. This section contains API references, protocol specifications, and technical documentation for integrating with Bookhoard.
+
+## 📚 API Documentation
+
+### Complete API Reference
+
+- **[API Reference](api-reference.md)** - Complete REST API reference
+  - Authentication
+  - User management
+  - Libraries
+  - Media items
+  - Reading progress
+  - Notes & highlights
+  - Analytics
+  - Book matching
+  - OPDS
+  - Sync protocols (KOReader, Kobo)
+  - WebSocket
+
+### Split Endpoint Documentation
+
+Browse individual endpoint documentation with interactive API Explorer:
+
+- **[API Documentation](api/INDEX.md)** - Split endpoint docs
+  - [Authentication](api/authentication/) - Register, login, tokens
+  - [Users](api/users/) - Profile management
+  - [Libraries](api/libraries/) - Library operations
+  - [Media Items](api/media-items/) - Book/ebook management
+  - [Progress](api/progress/) - Reading progress tracking
+  - [Notes](api/notes/) - User notes
+  - [Highlights](api/highlights/) - Book highlights
+  - [Ratings](api/ratings/) - Book ratings
+  - [Devices](api/devices/) - Device management
+  - [Analytics](api/analytics/) - Usage statistics
+  - [Book Matching](api/book-matching/) - Search and link books
+  - [Collections](api/collections/) - Collection management
+  - [OPDS](api/opds/) - Open Publication Distribution
+  - [Sync Protocols](api/sync/) - KOReader and Kobo sync
+  - [WebSocket](api/websocket/) - Real-time events
+
+### Collections API
+
+- **[Collections API](collections-api.md)** - Complete collections API reference
+  - Create and manage collections
+  - Auto-assign rules
+  - Test rules
+  - Bulk operations
+  - Device shelf mappings
+
+## 🔌 Protocol Specifications
+
+### Sync Protocols
+
+- **[Kobo Sync Protocol](api/sync/kobo-protocol.md)** - Kobo device sync protocol
+  - Kobo markup sync
+  - Library fetch
+  - Authentication
+
+- **[KOReader Sync Protocol](api/sync/koreader-protocol.md)** - KOReader sync protocol
+  - Progress sync
+  - Metadata fetch
+  - Conflict handling
+
+### WebSocket Protocol
+
+- **[WebSocket API](websocket-api.md)** - Real-time sync and events
+  - Connection flow
+  - Message format
+  - Event types
+  - Authentication
+
+---
+
+**Looking for user documentation?** See the [User Portal](../user/INDEX.md)
+**Need to deploy?** See the [Operations Portal](../operations/INDEX.md)
diff --git a/docs/API_REFERENCE.md b/docs/developer/api-reference.md
similarity index 100%
rename from docs/API_REFERENCE.md
rename to docs/developer/api-reference.md
diff --git a/docs/api/INDEX.md b/docs/developer/api/INDEX.md
similarity index 91%
rename from docs/api/INDEX.md
rename to docs/developer/api/INDEX.md
index ea3a1a4..4a6299a 100644
--- a/docs/api/INDEX.md
+++ b/docs/developer/api/INDEX.md
@@ -15,7 +15,7 @@ Complete reference for Bookhoard REST API endpoints.
 - [Devices](devices/) - Device registration and sync
 - [Analytics](analytics/) - Usage statistics
 - [Book Matching](book-matching/) - Search and link books
-- [Collections](collections/) - See [COLLECTIONS_API.md](../COLLECTIONS_API.md)
+- [Collections](collections/) - See [Collections API](../collections-api.md)
 - [OPDS](opds/) - Open Publication Distribution
 - [Sync Protocols](sync/) - KOReader and Kobo sync
 - [WebSocket](websocket/) - Real-time sync events
@@ -64,7 +64,7 @@ See [Book Matching](book-matching/)
 
 ## Collections
 
-See [Collections API](../COLLECTIONS_API.md) or [Collections Endpoints](collections/)
+See [Collections API](../collections-api.md) or [Collections Endpoints](collections/)
 
 ## OPDS
 
diff --git a/docs/api/analytics/get_analytics.md b/docs/developer/api/analytics/get_analytics.md
similarity index 100%
rename from docs/api/analytics/get_analytics.md
rename to docs/developer/api/analytics/get_analytics.md
diff --git a/docs/api/authentication/login.md b/docs/developer/api/authentication/login.md
similarity index 100%
rename from docs/api/authentication/login.md
rename to docs/developer/api/authentication/login.md
diff --git a/docs/api/authentication/logout.md b/docs/developer/api/authentication/logout.md
similarity index 100%
rename from docs/api/authentication/logout.md
rename to docs/developer/api/authentication/logout.md
diff --git a/docs/api/authentication/refresh_token.md b/docs/developer/api/authentication/refresh_token.md
similarity index 100%
rename from docs/api/authentication/refresh_token.md
rename to docs/developer/api/authentication/refresh_token.md
diff --git a/docs/api/authentication/register.md b/docs/developer/api/authentication/register.md
similarity index 100%
rename from docs/api/authentication/register.md
rename to docs/developer/api/authentication/register.md
diff --git a/docs/api/book-matching/link_book.md b/docs/developer/api/book-matching/link_book.md
similarity index 100%
rename from docs/api/book-matching/link_book.md
rename to docs/developer/api/book-matching/link_book.md
diff --git a/docs/api/book-matching/search_books.md b/docs/developer/api/book-matching/search_books.md
similarity index 100%
rename from docs/api/book-matching/search_books.md
rename to docs/developer/api/book-matching/search_books.md
diff --git a/docs/api/collections/INDEX.md b/docs/developer/api/collections/INDEX.md
similarity index 84%
rename from docs/api/collections/INDEX.md
rename to docs/developer/api/collections/INDEX.md
index 4c88cd1..d01e0c3 100644
--- a/docs/api/collections/INDEX.md
+++ b/docs/developer/api/collections/INDEX.md
@@ -1,6 +1,6 @@
 # Collections API
 
-See [COLLECTIONS_API.md](../../COLLECTIONS_API.md) for complete collections documentation.
+See [Collections API](../../collections-api.md) for complete collections documentation.
 
 ## Quick Links
 
@@ -31,5 +31,5 @@ Collections allow you to organize your books into custom groups with automatic a
 
 ## See Also
 
-- [COLLECTIONS_API.md](../../COLLECTIONS_API.md) - Complete API reference
-- [Sync Guide](../../SYNC_USER_GUIDE.md) - How collections sync to devices
+- [Collections API](../../collections-api.md) - Complete API reference
+- [Sync Guide](../../user/sync-guide.md) - How collections sync to devices
diff --git a/docs/api/collections/add_auto_assign_rule.md b/docs/developer/api/collections/add_auto_assign_rule.md
similarity index 100%
rename from docs/api/collections/add_auto_assign_rule.md
rename to docs/developer/api/collections/add_auto_assign_rule.md
diff --git a/docs/api/collections/bulk_assign.md b/docs/developer/api/collections/bulk_assign.md
similarity index 100%
rename from docs/api/collections/bulk_assign.md
rename to docs/developer/api/collections/bulk_assign.md
diff --git a/docs/api/collections/create_collection.md b/docs/developer/api/collections/create_collection.md
similarity index 100%
rename from docs/api/collections/create_collection.md
rename to docs/developer/api/collections/create_collection.md
diff --git a/docs/api/collections/create_shelf_mapping.md b/docs/developer/api/collections/create_shelf_mapping.md
similarity index 100%
rename from docs/api/collections/create_shelf_mapping.md
rename to docs/developer/api/collections/create_shelf_mapping.md
diff --git a/docs/api/collections/delete_collection.md b/docs/developer/api/collections/delete_collection.md
similarity index 100%
rename from docs/api/collections/delete_collection.md
rename to docs/developer/api/collections/delete_collection.md
diff --git a/docs/api/collections/delete_shelf_mapping.md b/docs/developer/api/collections/delete_shelf_mapping.md
similarity index 100%
rename from docs/api/collections/delete_shelf_mapping.md
rename to docs/developer/api/collections/delete_shelf_mapping.md
diff --git a/docs/api/collections/get_collection.md b/docs/developer/api/collections/get_collection.md
similarity index 100%
rename from docs/api/collections/get_collection.md
rename to docs/developer/api/collections/get_collection.md
diff --git a/docs/api/collections/list_collections.md b/docs/developer/api/collections/list_collections.md
similarity index 100%
rename from docs/api/collections/list_collections.md
rename to docs/developer/api/collections/list_collections.md
diff --git a/docs/api/collections/remove_auto_assign_rule.md b/docs/developer/api/collections/remove_auto_assign_rule.md
similarity index 100%
rename from docs/api/collections/remove_auto_assign_rule.md
rename to docs/developer/api/collections/remove_auto_assign_rule.md
diff --git a/docs/api/collections/test_rule.md b/docs/developer/api/collections/test_rule.md
similarity index 100%
rename from docs/api/collections/test_rule.md
rename to docs/developer/api/collections/test_rule.md
diff --git a/docs/api/collections/update_collection.md b/docs/developer/api/collections/update_collection.md
similarity index 100%
rename from docs/api/collections/update_collection.md
rename to docs/developer/api/collections/update_collection.md
diff --git a/docs/api/devices/get_devices.md b/docs/developer/api/devices/get_devices.md
similarity index 100%
rename from docs/api/devices/get_devices.md
rename to docs/developer/api/devices/get_devices.md
diff --git a/docs/api/devices/list_devices.md b/docs/developer/api/devices/list_devices.md
similarity index 100%
rename from docs/api/devices/list_devices.md
rename to docs/developer/api/devices/list_devices.md
diff --git a/docs/api/devices/register_device.md b/docs/developer/api/devices/register_device.md
similarity index 100%
rename from docs/api/devices/register_device.md
rename to docs/developer/api/devices/register_device.md
diff --git a/docs/api/devices/revoke_device.md b/docs/developer/api/devices/revoke_device.md
similarity index 100%
rename from docs/api/devices/revoke_device.md
rename to docs/developer/api/devices/revoke_device.md
diff --git a/docs/api/highlights/create_highlight.md b/docs/developer/api/highlights/create_highlight.md
similarity index 100%
rename from docs/api/highlights/create_highlight.md
rename to docs/developer/api/highlights/create_highlight.md
diff --git a/docs/api/highlights/delete_highlight.md b/docs/developer/api/highlights/delete_highlight.md
similarity index 100%
rename from docs/api/highlights/delete_highlight.md
rename to docs/developer/api/highlights/delete_highlight.md
diff --git a/docs/api/highlights/get_highlights.md b/docs/developer/api/highlights/get_highlights.md
similarity index 100%
rename from docs/api/highlights/get_highlights.md
rename to docs/developer/api/highlights/get_highlights.md
diff --git a/docs/api/highlights/update_highlight.md b/docs/developer/api/highlights/update_highlight.md
similarity index 100%
rename from docs/api/highlights/update_highlight.md
rename to docs/developer/api/highlights/update_highlight.md
diff --git a/docs/api/libraries/add_library_folder.md b/docs/developer/api/libraries/add_library_folder.md
similarity index 100%
rename from docs/api/libraries/add_library_folder.md
rename to docs/developer/api/libraries/add_library_folder.md
diff --git a/docs/api/libraries/create_library.md b/docs/developer/api/libraries/create_library.md
similarity index 100%
rename from docs/api/libraries/create_library.md
rename to docs/developer/api/libraries/create_library.md
diff --git a/docs/api/libraries/get_library.md b/docs/developer/api/libraries/get_library.md
similarity index 100%
rename from docs/api/libraries/get_library.md
rename to docs/developer/api/libraries/get_library.md
diff --git a/docs/api/libraries/get_visible_libraries.md b/docs/developer/api/libraries/get_visible_libraries.md
similarity index 100%
rename from docs/api/libraries/get_visible_libraries.md
rename to docs/developer/api/libraries/get_visible_libraries.md
diff --git a/docs/api/libraries/set_library_visibility.md b/docs/developer/api/libraries/set_library_visibility.md
similarity index 100%
rename from docs/api/libraries/set_library_visibility.md
rename to docs/developer/api/libraries/set_library_visibility.md
diff --git a/docs/api/media-items/delete_media_item.md b/docs/developer/api/media-items/delete_media_item.md
similarity index 100%
rename from docs/api/media-items/delete_media_item.md
rename to docs/developer/api/media-items/delete_media_item.md
diff --git a/docs/api/media-items/filter_sort_media_items.md b/docs/developer/api/media-items/filter_sort_media_items.md
similarity index 100%
rename from docs/api/media-items/filter_sort_media_items.md
rename to docs/developer/api/media-items/filter_sort_media_items.md
diff --git a/docs/api/media-items/get_media_item.md b/docs/developer/api/media-items/get_media_item.md
similarity index 100%
rename from docs/api/media-items/get_media_item.md
rename to docs/developer/api/media-items/get_media_item.md
diff --git a/docs/api/media-items/list_media_items.md b/docs/developer/api/media-items/list_media_items.md
similarity index 100%
rename from docs/api/media-items/list_media_items.md
rename to docs/developer/api/media-items/list_media_items.md
diff --git a/docs/api/media-items/search_media_items.md b/docs/developer/api/media-items/search_media_items.md
similarity index 100%
rename from docs/api/media-items/search_media_items.md
rename to docs/developer/api/media-items/search_media_items.md
diff --git a/docs/api/media-items/update_media_item.md b/docs/developer/api/media-items/update_media_item.md
similarity index 100%
rename from docs/api/media-items/update_media_item.md
rename to docs/developer/api/media-items/update_media_item.md
diff --git a/docs/api/notes/create_note.md b/docs/developer/api/notes/create_note.md
similarity index 100%
rename from docs/api/notes/create_note.md
rename to docs/developer/api/notes/create_note.md
diff --git a/docs/api/notes/delete_note.md b/docs/developer/api/notes/delete_note.md
similarity index 100%
rename from docs/api/notes/delete_note.md
rename to docs/developer/api/notes/delete_note.md
diff --git a/docs/api/notes/get_notes.md b/docs/developer/api/notes/get_notes.md
similarity index 100%
rename from docs/api/notes/get_notes.md
rename to docs/developer/api/notes/get_notes.md
diff --git a/docs/api/notes/update_note.md b/docs/developer/api/notes/update_note.md
similarity index 100%
rename from docs/api/notes/update_note.md
rename to docs/developer/api/notes/update_note.md
diff --git a/docs/api/opds/acquisition.md b/docs/developer/api/opds/acquisition.md
similarity index 100%
rename from docs/api/opds/acquisition.md
rename to docs/developer/api/opds/acquisition.md
diff --git a/docs/api/opds/feeds.md b/docs/developer/api/opds/feeds.md
similarity index 100%
rename from docs/api/opds/feeds.md
rename to docs/developer/api/opds/feeds.md
diff --git a/docs/api/opds/publication.md b/docs/developer/api/opds/publication.md
similarity index 100%
rename from docs/api/opds/publication.md
rename to docs/developer/api/opds/publication.md
diff --git a/docs/api/progress/delete_progress.md b/docs/developer/api/progress/delete_progress.md
similarity index 100%
rename from docs/api/progress/delete_progress.md
rename to docs/developer/api/progress/delete_progress.md
diff --git a/docs/api/progress/get_progress.md b/docs/developer/api/progress/get_progress.md
similarity index 100%
rename from docs/api/progress/get_progress.md
rename to docs/developer/api/progress/get_progress.md
diff --git a/docs/api/progress/update_progress.md b/docs/developer/api/progress/update_progress.md
similarity index 100%
rename from docs/api/progress/update_progress.md
rename to docs/developer/api/progress/update_progress.md
diff --git a/docs/api/ratings/create_rating.md b/docs/developer/api/ratings/create_rating.md
similarity index 100%
rename from docs/api/ratings/create_rating.md
rename to docs/developer/api/ratings/create_rating.md
diff --git a/docs/api/ratings/get_ratings.md b/docs/developer/api/ratings/get_ratings.md
similarity index 100%
rename from docs/api/ratings/get_ratings.md
rename to docs/developer/api/ratings/get_ratings.md
diff --git a/docs/api/sync/kobo_protocol.md b/docs/developer/api/sync/kobo-protocol.md
similarity index 100%
rename from docs/api/sync/kobo_protocol.md
rename to docs/developer/api/sync/kobo-protocol.md
diff --git a/docs/api/sync/koreader_protocol.md b/docs/developer/api/sync/koreader-protocol.md
similarity index 100%
rename from docs/api/sync/koreader_protocol.md
rename to docs/developer/api/sync/koreader-protocol.md
diff --git a/docs/api/users/change_password.md b/docs/developer/api/users/change_password.md
similarity index 100%
rename from docs/api/users/change_password.md
rename to docs/developer/api/users/change_password.md
diff --git a/docs/api/users/get_profile.md b/docs/developer/api/users/get_profile.md
similarity index 100%
rename from docs/api/users/get_profile.md
rename to docs/developer/api/users/get_profile.md
diff --git a/docs/api/users/update_profile.md b/docs/developer/api/users/update_profile.md
similarity index 100%
rename from docs/api/users/update_profile.md
rename to docs/developer/api/users/update_profile.md
diff --git a/docs/api/users/update_theme.md b/docs/developer/api/users/update_theme.md
similarity index 100%
rename from docs/api/users/update_theme.md
rename to docs/developer/api/users/update_theme.md
diff --git a/docs/api/websocket/protocol.md b/docs/developer/api/websocket/protocol.md
similarity index 100%
rename from docs/api/websocket/protocol.md
rename to docs/developer/api/websocket/protocol.md
diff --git a/docs/COLLECTIONS_API.md b/docs/developer/collections-api.md
similarity index 100%
rename from docs/COLLECTIONS_API.md
rename to docs/developer/collections-api.md
diff --git a/docs/api/WEBSOCKET_API.md b/docs/developer/websocket-api.md
similarity index 100%
rename from docs/api/WEBSOCKET_API.md
rename to docs/developer/websocket-api.md
diff --git a/docs/operations/INDEX.md b/docs/operations/INDEX.md
new file mode 100644
index 0000000..36ee5fe
--- /dev/null
+++ b/docs/operations/INDEX.md
@@ -0,0 +1,34 @@
+# Operations Documentation
+
+Welcome to the Bookhoard operations documentation. This section contains guides for deploying, maintaining, and troubleshooting Bookhoard instances.
+
+## 🔧 Deployment
+
+### Quick Start
+
+1. **[Troubleshooting Guide](troubleshooting.md)** - Common deployment issues and solutions
+   - Environment variables setup
+   - Port conflicts
+   - Container runtime (Podman)
+   - Network configuration
+   - Performance optimization
+
+### Additional Deployment Guides
+
+**[Deployment Guide](deployment.md)** - Comprehensive deployment guide
+- *Coming Soon*
+
+## 🛠️ Maintenance
+
+**[Maintenance Guide](maintenance.md)** - Ongoing operations and maintenance
+- *Coming Soon*
+
+## 📊 Monitoring
+
+**[Monitoring Guide](monitoring.md)** - Monitoring and alerting
+- *Coming Soon*
+
+---
+
+**Looking for user documentation?** See the [User Portal](../user/INDEX.md)
+**Need API docs?** See the [Developer Portal](../developer/INDEX.md)
diff --git a/docs/TROUBLESHOOTING.md b/docs/operations/troubleshooting.md
similarity index 100%
rename from docs/TROUBLESHOOTING.md
rename to docs/operations/troubleshooting.md
diff --git a/docs/user/INDEX.md b/docs/user/INDEX.md
new file mode 100644
index 0000000..d00e5e5
--- /dev/null
+++ b/docs/user/INDEX.md
@@ -0,0 +1,52 @@
+# User Documentation
+
+Welcome to the Bookhoard user documentation. This section contains guides for using Bookhoard features, setting up devices, and configuring sync.
+
+## 📱 Device Setup
+
+Learn how to configure your e-reader devices to sync with Bookhoard:
+
+- **[Kobo Setup Guide](devices/kobo-setup.md)** - Complete guide for Kobo e-readers
+  - Device registration
+  - Sync configuration
+  - OPDS wireless book delivery
+  - Troubleshooting
+
+- **[KOReader Setup Guide](devices/koreader-setup.md)** - Complete guide for KOReader
+  - Installation on Kindle/Kobo/PocketBook
+  - Sync setup
+  - OPDS catalog access
+  - Troubleshooting
+
+## 🔄 Sync Configuration
+
+- **[Universal Sync Guide](sync-guide.md)** - Understanding and using sync features
+  - What is Universal Sync?
+  - Supported devices
+  - Book matching and auto-linking
+  - Conflict resolution
+  - Best practices
+
+## 🎨 Frontend Guide
+
+**[Frontend Guide](frontend-guide.md)** - Learn how to use the Bookhoard web interface
+- *Coming Soon*
+
+## 👤 User Areas
+
+**[User Areas Guide](user-areas.md)** - Managing your personal library and settings
+- *Coming Soon*
+
+## ⚙️ Settings
+
+**[Settings Guide](settings-guide.md)** - Configuring your Bookhoard preferences
+- *Coming Soon*
+
+## 🔐 Admin Features
+
+**[Admin Guide](admin-guide.md)** - Administrative functions and management
+- *Coming Soon*
+
+---
+
+**Looking for developer documentation?** See the [Developer Portal](../developer/INDEX.md)
diff --git a/docs/user/admin-guide.md b/docs/user/admin-guide.md
new file mode 100644
index 0000000..155153f
--- /dev/null
+++ b/docs/user/admin-guide.md
@@ -0,0 +1,15 @@
+# Admin Guide
+
+**Coming Soon**
+
+This guide will cover:
+- User management
+- Library management
+- System monitoring
+- Analytics and reporting
+- Security settings
+- Backup and restore
+
+---
+
+*In the meantime, check out our [Operations Portal](../operations/)*
diff --git a/docs/devices/KOBO_SETUP.md b/docs/user/devices/kobo-setup.md
similarity index 99%
rename from docs/devices/KOBO_SETUP.md
rename to docs/user/devices/kobo-setup.md
index e1e0c19..ed673af 100644
--- a/docs/devices/KOBO_SETUP.md
+++ b/docs/user/devices/kobo-setup.md
@@ -560,9 +560,9 @@ To improve sync speed:
 ## Additional Resources
 
 - [Kobo Developer Documentation](https://help.kobo.com/hc/en-us)
-- [Bookhoard Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md)
-- [KOReader Setup Guide](KOBOREADER_SETUP.md)
-- [Bookhoard API Reference](API_REFERENCE.md)
+- [Bookhoard Universal Sync Guide](../sync-guide.md)
+- [KOReader Setup Guide](koreader-setup.md)
+- [Bookhoard API Reference](../../developer/api-reference.md)
 
 ## FAQ
 
diff --git a/docs/devices/KOREADER_SETUP.md b/docs/user/devices/koreader-setup.md
similarity index 99%
rename from docs/devices/KOREADER_SETUP.md
rename to docs/user/devices/koreader-setup.md
index 7329fb7..c003950 100644
--- a/docs/devices/KOREADER_SETUP.md
+++ b/docs/user/devices/koreader-setup.md
@@ -485,8 +485,8 @@ OPDSCompressionEnabled = true
 
 - [KOReader Documentation](https://github.com/koreader/koreader)
 - [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271)
-- [Bookhoard Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md)
-- [Kobo Setup Guide](KOBO_SETUP.md)
+- [Bookhoard Universal Sync Guide](../sync-guide.md)
+- [Kobo Setup Guide](kobo-setup.md)
 
 ## Support
 
diff --git a/docs/user/frontend-guide.md b/docs/user/frontend-guide.md
new file mode 100644
index 0000000..7d2ff8a
--- /dev/null
+++ b/docs/user/frontend-guide.md
@@ -0,0 +1,15 @@
+# Frontend Guide
+
+**Coming Soon**
+
+This guide will cover:
+- Navigating the Bookhoard web interface
+- Browsing and searching your library
+- Managing collections
+- Viewing reading progress
+- Using notes and highlights
+- Personalizing your experience
+
+---
+
+*In the meantime, check out our [Device Setup Guides](devices/)*
diff --git a/docs/user/settings-guide.md b/docs/user/settings-guide.md
new file mode 100644
index 0000000..59c7f0b
--- /dev/null
+++ b/docs/user/settings-guide.md
@@ -0,0 +1,14 @@
+# Settings Guide
+
+**Coming Soon**
+
+This guide will cover:
+- Account settings
+- Display preferences (themes, fonts)
+- Sync configuration
+- Device management
+- Privacy options
+
+---
+
+*In the meantime, check out our [Device Setup Guides](devices/)*
diff --git a/docs/SYNC_USER_GUIDE.md b/docs/user/sync-guide.md
similarity index 99%
rename from docs/SYNC_USER_GUIDE.md
rename to docs/user/sync-guide.md
index e311c72..2db0ac6 100644
--- a/docs/SYNC_USER_GUIDE.md
+++ b/docs/user/sync-guide.md
@@ -73,8 +73,8 @@
 
 For detailed device configuration instructions, see the appropriate setup guide:
 
-- **[Kobo Setup Guide](devices/KOBO_SETUP.md)** - Kobo e-reader configuration
-- **[KOReader Setup Guide](devices/KOREADER_SETUP.md)** - KOReader configuration
+- **[Kobo Setup Guide](devices/kobo-setup.md)** - Kobo e-reader configuration
+- **[KOReader Setup Guide](devices/koreader-setup.md)** - KOReader configuration
 
 ### Quick Overview
 
diff --git a/docs/user/user-areas.md b/docs/user/user-areas.md
new file mode 100644
index 0000000..9483fff
--- /dev/null
+++ b/docs/user/user-areas.md
@@ -0,0 +1,14 @@
+# User Areas Guide
+
+**Coming Soon**
+
+This guide will cover:
+- Managing your personal library
+- Uploading and organizing books
+- Creating and managing collections
+- Syncing across devices
+- Personal settings
+
+---
+
+*In the meantime, check out our [Sync Guide](sync-guide.md)*
diff --git a/internal/docs/http_handler.go b/internal/docs/http_handler.go
index a7a1967..367a232 100644
--- a/internal/docs/http_handler.go
+++ b/internal/docs/http_handler.go
@@ -247,10 +247,11 @@ func (h *HTTPHandler) APIHome(c echo.Context) error {
 		TOC:     []templates.TOCItem{},
 		Breadcrumb: []templates.BreadcrumbItem{
 			{Title: "Docs", URL: "/docs"},
+			{Title: "Developer", URL: "/docs/developer"},
 			{Title: "API Reference", URL: ""},
 		},
 		Category:   "API Reference",
-		SourceFile: "API_REFERENCE.md",
+		SourceFile: "developer/api-reference.md",
 	}
 
 	var buf bytes.Buffer
diff --git a/internal/docs/navigation.go b/internal/docs/navigation.go
index 58a80d9..b180245 100644
--- a/internal/docs/navigation.go
+++ b/internal/docs/navigation.go
@@ -100,22 +100,22 @@ func (h *DocsHandler) getDocTitle(docPath string) string {
 	switch filename {
 	case "INDEX.md":
 		return "Documentation Index"
-	case "API_REFERENCE.md":
+	case "developer/api-reference.md":
 		return "API Reference"
-	case "TROUBLESHOOTING.md":
+	case "developer/collections-api.md":
+		return "Collections API"
+	case "developer/websocket-api.md":
+		return "WebSocket API"
+	case "operations/troubleshooting.md":
 		return "Troubleshooting"
-	case "SYNC_USER_GUIDE.md":
+	case "user/sync-guide.md":
 		return "Sync Guide"
+	case "user/devices/kobo-setup.md":
+		return "Kobo Setup"
+	case "user/devices/koreader-setup.md":
+		return "KOReader Setup"
 	case "DEVELOPMENT.md":
 		return "Development Guide"
-	case "WEBSOCKET_API.md":
-		return "WebSocket API"
-	case "COLLECTIONS_API.md":
-		return "Collections API"
-	case "KOBO_SETUP.md":
-		return "Kobo Setup"
-	case "KOREADER_SETUP.md":
-		return "KOReader Setup"
 	}
 
 	return title