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