diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..9da87fd
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,138 @@
+# Provisioning Platform Documentation
+
+Complete documentation for the Provisioning Platform infrastructure automation system built with Nushell,
+Nickel, and Rust.
+
+## 📖 Browse Documentation
+
+All documentation is **directly readable** as markdown files in Git/GitHub—mdBook is optional.
+
+- **[Table of Contents](src/SUMMARY.md)** – Complete documentation index (188+ pages)
+- **[Browse src/ directory](src/)** – All markdown files organized by topic
+
+---
+
+## 🚀 Quick Navigation
+
+### For Users & Operators
+
+- **[Getting Started](src/getting-started/)** – Installation, setup, and first deployment
+- **[Operations Guide](src/operations/)** – Deployment, monitoring, orchestrator management
+- **[Troubleshooting](src/troubleshooting/troubleshooting-guide.md)** – Common issues and solutions
+- **[Security](src/security/)** – Authentication, encryption, secrets management
+
+### For Developers & Architects
+
+- **[Architecture Overview](src/architecture/)** – System design and integration patterns
+- **[Infrastructure Guide](src/infrastructure/)** – CLI, configuration system, workspaces
+- **[Development Guide](src/development/)** – Extensions, providers, taskservs, build system
+- **[API Reference](src/api-reference/)** – REST API, WebSocket, SDKs, integration examples
+
+### For Advanced Users
+
+- **[Deployment Guides](src/guides/)** – Multi-provider setup, customization, infrastructure examples
+- **[Integration Guides](src/integration/)** – Gitea, OCI, service mesh, secrets integration
+- **[Testing](src/testing/)** – Test environment setup and validation
+
+---
+
+## 📚 Documentation Structure
+
+```
+provisioning/docs/
+├── README.md                    # This file – navigation hub
+├── book.toml                    # mdBook configuration
+├── src/                         # Source markdown files (version-controlled)
+│   ├── SUMMARY.md              # Complete table of contents
+│   ├── getting-started/        # Installation and setup
+│   ├── architecture/           # System design and ADRs
+│   ├── infrastructure/         # CLI, configuration, workspaces
+│   ├── operations/             # Deployment, orchestrator, monitoring
+│   ├── development/            # Extensions, providers, build system
+│   ├── api-reference/          # APIs and SDKs
+│   ├── security/               # Authentication, secrets, encryption
+│   ├── integration/            # Third-party integrations
+│   ├── guides/                 # How-to guides and examples
+│   ├── troubleshooting/        # Common issues
+│   └── ...                     # 12 other sections
+├── book/                        # Generated HTML output (Git-ignored)
+└── examples/                    # Example workspace configurations
+```
+
+### Why `src/` subdirectory
+
+This is the **standard mdBook convention**:
+- **Source (`src/`)**: Version-controlled markdown files, directly readable
+- **Output (`book/`)**: Generated HTML/CSS/JS, Git-ignored (regenerated on build)
+
+This separation allows the same source files to generate multiple output formats (HTML, PDF, EPUB) without
+cluttering the version-controlled repository.
+
+---
+
+## 🔨 Building HTML with mdBook
+
+If you prefer a formatted HTML website with search, themes, and copy buttons, build with mdBook:
+
+### Prerequisites
+
+```bash
+cargo install mdbook
+```
+
+### Build & Serve
+
+```bash
+# Navigate to docs directory
+cd provisioning/docs
+
+# Build HTML to book/ directory
+mdbook build
+
+# Serve locally at http://localhost:3000 (with live reload)
+mdbook serve
+```
+
+### Output
+
+Generated HTML is available in `provisioning/docs/book/` after building.
+
+**Note**: mdBook is entirely optional. The markdown files in `src/` work perfectly fine in any Git
+viewer or text editor.
+
+---
+
+## 📖 Reading Markdown Directly
+
+All documentation is standard GitHub Flavored Markdown. You can:
+
+- **GitHub/GitLab**: Click `provisioning/docs/src/` and browse directly
+- **Local Git**: Clone the repo and open any `.md` file in your editor
+- **Text Search**: Use `grep` or your editor's search to find topics across all markdown files
+- **mdBook (optional)**: Build HTML for formatted reading with search and theming
+
+---
+
+## 🔗 Key Reference Pages
+
+| Document                                                                       | Purpose                           |
+| ------------------------------------------------------------------------------ | --------------------------------- |
+| [System Overview](src/architecture/system-overview.md)                         | High-level architecture           |
+| [Installation Guide](src/getting-started/installation-guide.md)                | Step-by-step setup                |
+| [CLI Reference](src/infrastructure/cli-reference.md)                           | Command reference                 |
+| [Configuration System](src/infrastructure/configuration-system.md)             | Config management                 |
+| [Security System](src/security/security-system.md)                             | Authentication & encryption       |
+| [Orchestrator](src/operations/orchestrator.md)                                 | Service orchestration             |
+| [Workspace Guide](src/infrastructure/workspaces/workspace-guide.md)            | Infrastructure workspaces         |
+| [ADRs](src/architecture/adr/)                                                  | Architecture Decision Records     |
+
+---
+
+## ❓ Questions
+
+- **Getting started** → Start with [Installation Guide](src/getting-started/installation-guide.md)
+- **Having issues** → Check [Troubleshooting](src/troubleshooting/troubleshooting-guide.md)
+- **Looking for API docs** → See [API Reference](src/api-reference/)
+- **Want architecture details** → Read [Architecture Overview](src/architecture/architecture-overview.md)
+
+For complete navigation, see [Table of Contents](src/SUMMARY.md).