Vapora/docs/README.md

# VAPORA Documentation

Complete user-facing documentation for VAPORA, an intelligent development orchestration platform.

## Quick Navigation

- **[Getting Started](getting-started.md)** — Start here
- **[Quickstart](quickstart.md)** — Quick setup guide
- **[Setup & Deployment](setup/)** — Installation, configuration, deployment
- **[Features](features/)** — Capabilities and overview
- **[Architecture](architecture/)** — Design, planning, and system overview
- **[Integrations](integrations/)** — Integration guides and APIs
- **[Branding](branding.md)** — Brand assets and guidelines
- **[Executive Summary](executive/)** — Executive-level summaries

## Documentation Structure

```
docs/
├── README.md                    (this file - directory index)
├── getting-started.md           (entry point)
├── quickstart.md                (quick setup)
├── branding.md                  (brand guidelines)
├── setup/                       (installation & deployment)
│   ├── README.md
│   ├── setup-guide.md
│   ├── deployment.md
│   ├── tracking-setup.md
│   └── ...
├── features/                    (product capabilities)
│   ├── README.md
│   └── overview.md
├── architecture/                (design & planning)
│   ├── README.md
│   ├── project-plan.md
│   ├── phase1-integration.md
│   ├── completion-report.md
│   └── ...
├── integrations/                (integration guides)
│   ├── README.md
│   ├── doc-lifecycle.md
│   └── ...
└── executive/                   (executive summaries)
    ├── README.md
    ├── executive-summary.md
    └── resumen-ejecutivo.md
```

## mdBook Integration

### Overview

This documentation project is fully integrated with **mdBook**, a command-line tool for building books from markdown. All markdown files in this directory are automatically indexed and linked through the mdBook system.

### Directory Structure for mdBook

```
docs/
├── book.toml                        (mdBook configuration)
├── src/
│   ├── SUMMARY.md                   (table of contents - auto-generated)
│   ├── intro.md                     (landing page)
├── theme/                           (custom styling)
│   ├── index.hbs                    (HTML template)
│   └── vapora-custom.css            (custom CSS theme)
├── book/                            (generated output - .gitignored)
│   └── index.html
├── .gitignore                       (excludes build artifacts)
│
├── README.md                        (this file)
├── getting-started.md               (entry points)
├── quickstart.md
├── examples-guide.md                (examples documentation)
├── tutorials/                       (learning tutorials)
│
├── setup/                           (installation & deployment)
├── features/                        (product capabilities)
├── architecture/                    (system design)
├── adrs/                            (architecture decision records)
├── integrations/                    (integration guides)
├── operations/                      (runbooks & procedures)
└── disaster-recovery/               (recovery procedures)
```

### Building the Documentation

**Install mdBook (if not already installed):**

```bash
cargo install mdbook
```

**Build the static site:**

```bash
cd docs
mdbook build
```

Output will be in `docs/book/` directory.

**Serve locally for development:**

```bash
cd docs
mdbook serve
```

Then open `http://localhost:3000` in your browser. Changes to markdown files will automatically rebuild.

### Documentation Guidelines

#### File Naming
- **Root markdown**: UPPERCASE (README.md, CHANGELOG.md)
- **Content markdown**: lowercase (getting-started.md, setup-guide.md)
- **Multi-word files**: kebab-case (setup-guide.md, disaster-recovery.md)

#### Structure Requirements
- Each subdirectory **must** have a README.md
- Use relative paths for internal links: `[link](../other-file.md)`
- Add proper heading hierarchy: Start with h2 (##) in content files

#### Markdown Compliance (markdownlint)
1. **Code Blocks (MD031, MD040)**
   - Add blank line before and after fenced code blocks
   - Always specify language: \`\`\`bash, \`\`\`rust, \`\`\`toml
   - Use \`\`\`text for output/logs

2. **Lists (MD032)**
   - Add blank line before and after lists

3. **Headings (MD022, MD001, MD026, MD024)**
   - Add blank line before and after headings
   - Heading levels increment by one
   - No trailing punctuation
   - No duplicate heading names

### mdBook Configuration (book.toml)

Key settings:

```toml
[book]
title = "VAPORA Platform Documentation"
src = "src"                    # Where mdBook reads SUMMARY.md
build-dir = "book"             # Where output is generated

[output.html]
theme = "theme"                # Path to custom theme
default-theme = "light"
edit-url-template = "https://github.com/.../edit/main/docs/{path}"
```

### Custom Theme

**Location**: `docs/theme/`

- `index.hbs` — HTML template
- `vapora-custom.css` — Custom styling with VAPORA branding

Features:
- Professional blue/violet color scheme
- Responsive design (mobile-friendly)
- Dark mode support
- Custom syntax highlighting
- Print-friendly styles

### Content Organization

The `src/SUMMARY.md` file automatically indexes all documentation:

```
# VAPORA Documentation

## [Introduction](../README.md)

## Getting Started
- [Quick Start](../getting-started.md)
- [Quickstart Guide](../quickstart.md)

## Setup & Deployment
- [Setup Overview](../setup/README.md)
- [Setup Guide](../setup/setup-guide.md)
...
```

**No manual updates needed** — SUMMARY.md structure remains constant as new docs are added to existing sections.

### Deployment

**GitHub Pages:**

```bash
# Build the book
mdbook build

# Commit and push
git add docs/book/
git commit -m "chore: update documentation"
git push origin main
```

Configure GitHub repository settings:
- Source: `main` branch
- Path: `docs/book/`
- Custom domain: docs.vapora.io (optional)

**Docker (for CI/CD):**

```dockerfile
FROM rust:latest
RUN cargo install mdbook

WORKDIR /docs
COPY . .
RUN mdbook build

# Output in /docs/book/
```

### Troubleshooting

| Issue | Solution |
|-------|----------|
| Links broken in mdBook | Use relative paths: `../file.md` not `file.md` |
| Theme not applying | Ensure `theme/` directory exists, run `mdbook build --no-create-missing` |
| Search not working | Rebuild with `mdbook build` |
| Build fails | Check for invalid TOML in `book.toml` |

### Quality Assurance

**Before committing documentation:**

```bash
# Lint markdown
markdownlint docs/**/*.md

# Build locally
cd docs && mdbook build

# Verify structure
cd docs && mdbook serve
# Open http://localhost:3000 and verify navigation
```

### CI/CD Integration

Add to `.github/workflows/docs.yml`:

```yaml
name: Documentation

on:
  push:
    paths:
      - 'docs/**'
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: peaceiris/actions-mdbook@v4
      - run: cd docs && mdbook build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/book
```

---

## Content Standards

Ensure all documents follow:
- Lowercase filenames (except README.md)
- Kebab-case for multi-word files
- Each subdirectory has README.md
- Proper heading hierarchy
- Clear, concise language
- Code examples when applicable
- Cross-references to related docs