provisioning/docs/README.md

# 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

```bash
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
bash
cargo install mdbook
```

### Build & Serve

```bash
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).