## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# VAPORA Documentation

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

## Quick Navigation

- Getting Started — Start here
- Quickstart — Quick setup guide
- Setup & Deployment — Installation, configuration, deployment
- Features — Capabilities and overview
- Architecture — Design, planning, and system overview
- Integrations — Integration guides and APIs
- Branding — Brand assets and guidelines
- Executive Summary — 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):

    cargo install mdbook

Build the static site:

    cd docs
    mdbook build

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

Serve locally for development:

    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:

    [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:

    # 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):

    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:

    # 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`:

    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