# TODO: Documentation System

**Branch:** `v20260326-02-documentation-audit-batch3`
**Date Started:** 2026-02-07
**Date Updated:** 2026-03-26 (Latest: Batch 3 Settings documentation completed)
**Status:** In Progress - documentation audit batches 1-3 completed; remaining: Mail Import re-validation, Troubleshooting pages, Sidebar Layout v2 consistency pass

---

## ✅ Validation Update (2026-03-26)

This TODO was re-checked against the current codebase and documentation templates.

Findings:
- The progress metrics in this file are outdated (`19/33`) and no longer reflect the repository state.
- The documentation template tree currently contains **39 files** under `containers/backupchecks/src/templates/documentation`.
- Because the app layout and multiple workflows changed after the original documentation wave, **all documentation pages require content review** for functional correctness (not only layout styling).

Decision:
- Keep this TODO active.
- Treat this as a full documentation audit task: verify each page against current UI/routes/behavior and update screenshots/text where needed.

---

## 🧾 Review Checklist (2026-03-26)

Gebruik deze lijst voor de volledige inhoudsreview tegen de huidige applicatie.

**Legenda**
- `P1` = hoge prioriteit (kritieke workflows / grootste kans op afwijkingen)
- `P2` = normale prioriteit
- `P3` = lage prioriteit

### Global checks (voor elke pagina)
- [ ] Route, paginatitel en navigatiepad kloppen met huidige UI
- [ ] Terminologie klopt met huidige labels/knoppen in de app
- [ ] Screenshots zijn actueel (nieuwe layout) of vervangen/verwijderd
- [ ] Tekst verwijst niet naar verwijderde/gewijzigde functies
- [ ] Role-based behavior (admin/operator/viewer/reporter) klopt

### Missing documentation topics (new pages required)
- [x] `[P1]` Cove Accounts + Cove run detail flow documenteren
- [x] `[P1]` Veeam Cloud Connect accounts/run flow documenteren
- [x] `[P1]` Run Checks Autotask "Link existing" gedrag updaten (incl. cross-company)
- [ ] `[P1]` Sidebar layout v2 consistent door alle docs verwerken

### Page-by-page review
#### Getting Started
- [ ] `[P2]` getting-started/what-is-backupchecks
- [ ] `[P2]` getting-started/first-login
- [ ] `[P2]` getting-started/quick-start

#### User Management
- [ ] `[P2]` users/users-and-roles
- [ ] `[P2]` users/login-authentication
- [ ] `[P2]` users/profile-settings

#### Customers & Jobs
- [ ] `[P2]` customers-jobs/managing-customers
- [ ] `[P2]` customers-jobs/configuring-jobs
- [ ] `[P2]` customers-jobs/approved-jobs
- [ ] `[P2]` customers-jobs/job-schedules

#### Mail & Import
- [ ] `[P1]` mail-import/setup
- [ ] `[P1]` mail-import/inbox-management
- [ ] `[P1]` mail-import/mail-parsing
- [ ] `[P1]` mail-import/auto-import

#### Backup Review
- [ ] `[P1]` backup-review/approving-backups
- [ ] `[P1]` backup-review/daily-jobs
- [ ] `[P1]` backup-review/run-checks-modal
- [ ] `[P1]` backup-review/overrides
- [ ] `[P1]` backup-review/remarks-tickets

#### Reports
- [ ] `[P1]` reports/creating-reports
- [ ] `[P1]` reports/relative-periods
- [ ] `[P1]` reports/scheduling
- [ ] `[P1]` reports/exporting-data

#### Autotask Integration
- [x] `[P1]` autotask/setup-configuration
- [x] `[P1]` autotask/company-mapping
- [x] `[P1]` autotask/creating-tickets
- [x] `[P1]` autotask/ticket-management

#### Settings
- [x] `[P1]` settings/general
- [x] `[P1]` settings/mail-configuration
- [x] `[P1]` settings/autotask-integration
- [x] `[P1]` settings/entra-sso
- [x] `[P1]` settings/reporting-settings
- [x] `[P1]` settings/user-management
- [x] `[P1]` settings/maintenance

#### Troubleshooting
- [ ] `[P2]` troubleshooting/common-issues
- [ ] `[P2]` troubleshooting/faq
- [ ] `[P2]` troubleshooting/support-contact

---

## 🔎 Batch 1 Findings (P1) — 2026-03-26

### A. Immediate correctness fixes (existing content)
- [x] `documentation/backup-review/daily-jobs.html`
  - Remove/replace incorrect claim that successful jobs are automatically reviewed.
  - Align workflow text with current behavior: review is handled via Run Checks job-level review.
- [x] `documentation/backup-review/approving-backups.html`
  - Replace wording "select multiple runs" with "select multiple jobs" where bulk review is described.
  - Re-verify Daily Jobs vs Run Checks role split text for current operational flow.
- [x] `documentation/backup-review/run-checks-modal.html`
  - Fix broken cross-link: `url_for('documentation.page', section='autotask', page='overview')` does not exist.
  - Replace with valid links to existing Autotask pages.
- [x] `documentation/backup-review/remarks-tickets.html`
  - Fix same broken `autotask/overview` link.
  - Re-check Autotask behavior section against current link-existing/create/resolve-note flow.

### B. Placeholder pages that require full rewrite (currently "Coming Soon")
- [ ] `documentation/reports/creating-reports.html`
- [ ] `documentation/reports/relative-periods.html`
- [ ] `documentation/reports/scheduling.html`
- [ ] `documentation/reports/exporting-data.html`
- [x] `documentation/autotask/setup-configuration.html`
- [x] `documentation/autotask/company-mapping.html`
- [x] `documentation/autotask/creating-tickets.html`
- [x] `documentation/autotask/ticket-management.html`
- [x] `documentation/settings/general.html`
- [x] `documentation/settings/mail-configuration.html`
- [x] `documentation/settings/autotask-integration.html`
- [x] `documentation/settings/reporting-settings.html`
- [x] `documentation/settings/user-management.html`
- [x] `documentation/settings/maintenance.html`

### C. Pages with content present but requiring targeted re-validation
- [x] `documentation/settings/entra-sso.html`
  - Verify navigation path labels (Integrations wording/layout) against current settings UI.
  - Keep untested warning unless production validation has been completed.
- [ ] `documentation/mail-import/setup.html`
  - Re-check exact settings navigation wording and folder-browser flow against current UI labels.
- [ ] `documentation/mail-import/auto-import.html`
  - Re-check references to Logging page path/wording and Imports section labels.

---

## 🔎 Batch 2 Findings (P1) — 2026-03-26 (Completed)

### A. Autotask docs rewritten from placeholders
- [x] `documentation/autotask/setup-configuration.html`
- [x] `documentation/autotask/company-mapping.html`
- [x] `documentation/autotask/creating-tickets.html`
- [x] `documentation/autotask/ticket-management.html`

### B. Autotask behavior alignment fixes
- [x] Documented `Link existing` cross-company behavior for shared/umbrella tickets.
- [x] Removed references to non-existent `autotask/overview` page and replaced broken links.
- [x] Re-validated ticket lifecycle notes (create/link/resolve note) against current Run Checks behavior.

---

## 🔎 Batch 3 Findings (P1) — 2026-03-26 (Completed)

### A. Settings docs rewritten from placeholders
- [x] `documentation/settings/general.html`
- [x] `documentation/settings/mail-configuration.html`
- [x] `documentation/settings/autotask-integration.html`
- [x] `documentation/settings/reporting-settings.html`
- [x] `documentation/settings/user-management.html`
- [x] `documentation/settings/maintenance.html`

### B. Settings content alignment notes
- [x] Re-validated `documentation/settings/entra-sso.html` against current Settings -> Integrations navigation and field names.
- [x] Reporting page updated to explicitly document current status: no dedicated Reporting settings card is available in Settings.
- [x] Removed all placeholder text from Settings documentation pages.

---

## 📊 Current Progress

### Completed Sections ✅

**Phase 1: Core Infrastructure (COMPLETE)**
- ✅ Routes and blueprint setup
- ✅ Navigation sidebar with icons
- ✅ Base layout template
- ✅ CSS styling with dark mode support
- ✅ Breadcrumb navigation
- ✅ Previous/Next pagination
- ✅ Documentation menu item in navbar

**Phase 2: Getting Started (3/3 pages - COMPLETE)**
- ✅ What is BackupChecks?
- ✅ First Login & Dashboard
- ✅ Quick Start Checklist

**Phase 3: Users Section (3/3 pages - COMPLETE)**
- ✅ Users & Roles (with user-management.png screenshot)
- ✅ Login & Authentication (with Firefox recommendation)
- ✅ Profile Settings (with user-settings.png screenshot)

**Phase 3: Customers & Jobs Section (4/4 pages - COMPLETE)**
- ✅ Managing Customers (with edit-customer.png, new-customers.png)
- ✅ Configuring Jobs (with approve-job.png)
- ✅ Approved Jobs (with job-details.png)
- ✅ Job Schedules (with schedule-indicators.png)

**Phase 3: Mail & Import (4/4 pages - COMPLETE)**
- ✅ Mail Import Setup
- ✅ Inbox Management
- ✅ Mail Parsing
- ✅ Auto-Import Configuration

**Phase 3: Backup Review (5/5 pages - COMPLETE)**
- ✅ Approving Backups (corrected for per-job review)
- ✅ Daily Jobs View
- ✅ Run Checks Modal (corrected for per-job review, removed non-existent reviewed indicator)
- ✅ Overrides & Exceptions
- ✅ Remarks & Tickets

**Latest Corrections (2026-02-08):**
- Fixed per-job review mechanism documentation (review is per-JOB, not per individual run)
- Removed non-existent "reviewed indicator" from Run Checks Modal
- Corrected bulk review description from "select runs" to "select jobs"
- Updated Unmark Reviewed section to reflect per-job unmarking
- Removed incorrect statement that successful runs are automatically reviewed

### Screenshots Added (10 total)
1. user-management.png - User role checkboxes
2. user-settings.png - Password change form
3. edit-customer.png - Customer edit dialog with Autotask mapping
4. new-customers.png - Customer creation and CSV import/export
5. approve-job.png - Inbox email detail with customer selection
6. job-details.png - Job detail page with schedule and history
7. schedule-indicators.png - Daily Jobs schedule with run status indicators

### Remaining Work 🚧

**Phase 4: Advanced Features (10/14 pages complete)**
- Reports (0/4 pages)
- Autotask Integration (4/4 pages - COMPLETE)
- Settings (6/6 pages - COMPLETE)
- Troubleshooting (0/3 pages)

**Progress Summary:**
- ✅ Batch 1 documentation updates completed (Integrations + critical Run Checks wording/link fixes).
- ✅ Batch 2 documentation updates completed (Autotask section rewritten and aligned with current behavior).
- ✅ Batch 3 documentation updates completed (Settings section rewritten and revalidated).
- ⏳ Remaining focus: Mail Import re-validation pages, Troubleshooting pages, and final Sidebar Layout v2 consistency pass.

---

## 🎯 Goal

Add a static documentation system to BackupChecks for user onboarding and reference. A comprehensive guide explaining how the application works, accessible only to logged-in users.

---

## ✅ Requirements Summary

- **Format:** HTML templates (for full CSS control)
- **Structure:** Multiple pages with navigation menu
- **Menu Item:** "Documentation" with 📖 icon
- **Access:** Logged-in users only
- **Content:** Basic + Advanced topics (all features)
- **Language:** English only (app is not translated to Dutch)
- **Screenshots:** Yes, embedded in pages
- **Maintenance:** Static content updated via git (no in-app editing)

---

## 📋 Documentation Structure

### Navigation Menu (Left Sidebar)

```
Documentation 📖
├─ 🏠 Getting Started
│  ├─ What is BackupChecks?
│  ├─ First Login & Dashboard
│  └─ Quick Start Checklist
│
├─ 👥 User Management
│  ├─ Users & Roles
│  ├─ Login & Authentication
│  └─ Profile Settings
│
├─ 💼 Customers & Jobs
│  ├─ Managing Customers
│  ├─ Configuring Jobs
│  ├─ Approved Jobs
│  └─ Job Schedules
│
├─ 📧 Mail & Import
│  ├─ Mail Import Setup
│  ├─ Inbox Management
│  ├─ Mail Parsing
│  └─ Auto-Import Configuration
│
├─ ✅ Backup Review
│  ├─ Approving Backups
│  ├─ Daily Jobs View
│  ├─ Run Checks Modal
│  ├─ Overrides & Exceptions
│  └─ Remarks & Tickets
│
├─ 📊 Reports
│  ├─ Creating Reports
│  ├─ Relative Periods
│  ├─ Report Scheduling
│  └─ Exporting Data
│
├─ 🎫 Autotask Integration
│  ├─ Setup & Configuration
│  ├─ Company Mapping
│  ├─ Creating Tickets
│  └─ Ticket Management
│
├─ ⚙️ Settings
│  ├─ General Settings
│  ├─ Mail Configuration
│  ├─ Autotask Integration
│  ├─ Reporting Settings
│  ├─ User Management
│  └─ Maintenance
│
└─ ❓ Troubleshooting
   ├─ Common Issues
   ├─ FAQ
   └─ Support Contact
```

---

## 🎨 UI Design

### Layout Structure

```
┌─────────────────────────────────────────────────────┐
│ Navbar (standard app navbar)                        │
├──────────────┬──────────────────────────────────────┤
│              │                                       │
│  Navigation  │  Content Area                        │
│  Sidebar     │                                       │
│  (250px)     │  ┌─ Breadcrumb ───────────────────┐  │
│              │  │ Documentation > Getting Started │  │
│  📖 Docs     │  └─────────────────────────────────┘  │
│              │                                       │
│  🏠 Getting  │  <h1>What is BackupChecks?</h1>     │
│     Started  │                                       │
│   • What is  │  <p>BackupChecks is a...</p>         │
│   • First    │                                       │
│   • Quick    │  <img src="..." />                   │
│              │                                       │
│  👥 Users    │  <h2>Key Features</h2>               │
│   • Users &  │  <ul>...                             │
│   • Login    │                                       │
│              │  ┌─ Next/Previous ──────────────┐    │
│  💼 Customer │  │ ← Previous  |  Next →        │    │
│   • Managing │  └───────────────────────────────┘    │
│   • Config   │                                       │
│              │                                       │
│  ...         │                                       │
│              │                                       │
│              │                                       │
│              │                                       │
└──────────────┴──────────────────────────────────────┘
```

### Navigation Sidebar (Fixed)
- Fixed position (scrolls with page)
- Collapsible sections (categories)
- Active page highlighted
- Icons per section
- Responsive: collapse to hamburger on mobile

### Content Area
- Max-width for readability (800-900px)
- Breadcrumb navigation
- H1/H2/H3 hierarchy
- Code blocks with syntax highlighting
- Screenshots with captions
- Tables for settings/options
- Info/warning/tip callout boxes
- Next/Previous navigation at bottom

---

## 📂 File Structure

```
containers/backupchecks/src/
├── backend/app/main/
│   └── routes_documentation.py          # NEW: Documentation routes
│
├── templates/
│   ├── documentation/
│   │   ├── base.html                    # Base layout with sidebar
│   │   ├── _navigation.html             # Sidebar navigation menu
│   │   ├── getting-started/
│   │   │   ├── what-is-backupchecks.html
│   │   │   ├── first-login.html
│   │   │   └── quick-start.html
│   │   ├── users/
│   │   │   ├── users-and-roles.html
│   │   │   ├── login-authentication.html
│   │   │   └── profile-settings.html
│   │   ├── customers-jobs/
│   │   │   ├── managing-customers.html
│   │   │   ├── configuring-jobs.html
│   │   │   ├── approved-jobs.html
│   │   │   └── job-schedules.html
│   │   ├── mail-import/
│   │   │   ├── setup.html
│   │   │   ├── inbox-management.html
│   │   │   ├── mail-parsing.html
│   │   │   └── auto-import.html
│   │   ├── backup-review/
│   │   │   ├── approving-backups.html
│   │   │   ├── daily-jobs.html
│   │   │   ├── run-checks-modal.html
│   │   │   ├── overrides.html
│   │   │   └── remarks-tickets.html
│   │   ├── reports/
│   │   │   ├── creating-reports.html
│   │   │   ├── relative-periods.html
│   │   │   ├── scheduling.html
│   │   │   └── exporting-data.html
│   │   ├── autotask/
│   │   │   ├── setup-configuration.html
│   │   │   ├── company-mapping.html
│   │   │   ├── creating-tickets.html
│   │   │   └── ticket-management.html
│   │   ├── settings/
│   │   │   ├── general.html
│   │   │   ├── mail-configuration.html
│   │   │   ├── autotask-integration.html
│   │   │   ├── reporting-settings.html
│   │   │   ├── user-management.html
│   │   │   └── maintenance.html
│   │   └── troubleshooting/
│   │       ├── common-issues.html
│   │       ├── faq.html
│   │       └── support-contact.html
│   │
│   └── layout/base.html                 # Update: add Documentation menu item
│
└── static/
    ├── css/
    │   └── documentation.css            # NEW: Documentation-specific styles
    └── images/
        └── documentation/               # NEW: Screenshots folder
            ├── dashboard-overview.png
            ├── customer-list.png
            ├── job-configuration.png
            ├── inbox-view.png
            └── ... (more screenshots)
```

**Total pages to create:** ~30 HTML pages

---

## 🔧 Implementation Plan

### Phase 1: Core Structure

#### 1A. Routes Setup

**File:** `containers/backupchecks/src/backend/app/main/routes_documentation.py`

```python
from flask import Blueprint, render_template
from flask_login import login_required

doc_bp = Blueprint('documentation', __name__, url_prefix='/documentation')

# Documentation structure (for navigation and routing)
DOCUMENTATION_STRUCTURE = {
    'getting-started': {
        'title': 'Getting Started',
        'icon': '🏠',
        'pages': [
            {'slug': 'what-is-backupchecks', 'title': 'What is BackupChecks?'},
            {'slug': 'first-login', 'title': 'First Login & Dashboard'},
            {'slug': 'quick-start', 'title': 'Quick Start Checklist'},
        ]
    },
    'users': {
        'title': 'User Management',
        'icon': '👥',
        'pages': [
            {'slug': 'users-and-roles', 'title': 'Users & Roles'},
            {'slug': 'login-authentication', 'title': 'Login & Authentication'},
            {'slug': 'profile-settings', 'title': 'Profile Settings'},
        ]
    },
    # ... (all other sections)
}

def get_navigation_context(current_section=None, current_page=None):
    """Build navigation context with active states."""
    return {
        'structure': DOCUMENTATION_STRUCTURE,
        'current_section': current_section,
        'current_page': current_page
    }

def get_prev_next(section, page_slug):
    """Get previous and next page for navigation."""
    # Flatten all pages into single list
    all_pages = []
    for sect_key, sect_data in DOCUMENTATION_STRUCTURE.items():
        for page in sect_data['pages']:
            all_pages.append({
                'section': sect_key,
                'slug': page['slug'],
                'title': page['title']
            })

    # Find current page index
    current_idx = None
    for i, p in enumerate(all_pages):
        if p['section'] == section and p['slug'] == page_slug:
            current_idx = i
            break

    if current_idx is None:
        return None, None

    prev_page = all_pages[current_idx - 1] if current_idx > 0 else None
    next_page = all_pages[current_idx + 1] if current_idx < len(all_pages) - 1 else None

    return prev_page, next_page

@doc_bp.route('/')
@doc_bp.route('/index')
@login_required
def index():
    """Documentation home - redirect to first page."""
    return redirect(url_for('documentation.page', section='getting-started', page='what-is-backupchecks'))

@doc_bp.route('/<section>/<page>')
@login_required
def page(section, page):
    """Render a documentation page."""
    # Validate section and page exist
    if section not in DOCUMENTATION_STRUCTURE:
        abort(404)

    section_data = DOCUMENTATION_STRUCTURE[section]
    page_exists = any(p['slug'] == page for p in section_data['pages'])
    if not page_exists:
        abort(404)

    # Get page title
    page_title = next(p['title'] for p in section_data['pages'] if p['slug'] == page)

    # Get navigation context
    nav_context = get_navigation_context(section, page)

    # Get prev/next pages
    prev_page, next_page = get_prev_next(section, page)

    # Render template
    template_path = f'documentation/{section}/{page}.html'
    return render_template(
        template_path,
        page_title=page_title,
        section_title=section_data['title'],
        navigation=nav_context,
        prev_page=prev_page,
        next_page=next_page
    )
```

#### 1B. Register Blueprint

**File:** `containers/backupchecks/src/backend/app/__init__.py`

```python
# Import documentation blueprint
from .main.routes_documentation import doc_bp

# Register blueprint
app.register_blueprint(doc_bp)
```

#### 1C. Add Menu Item

**File:** `containers/backupchecks/src/templates/layout/base.html`

Add to navigation menu (after existing items):

```html
<li class="nav-item">
  <a class="nav-link {% if request.path.startswith('/documentation') %}active{% endif %}"
     href="{{ url_for('documentation.index') }}">
    <span class="nav-icon">📖</span>
    Documentation
  </a>
</li>
```

#### 1D. Base Layout Template

**File:** `containers/backupchecks/src/templates/documentation/base.html`

```html
{% extends "layout/base.html" %}

{% block extra_css %}
<link rel="stylesheet" href="{{ url_for('static', filename='css/documentation.css') }}">
{% endblock %}

{% block content %}
<div class="documentation-container">
  <div class="row g-0">
    <!-- Sidebar Navigation -->
    <div class="col-12 col-lg-3 doc-sidebar-wrapper">
      {% include 'documentation/_navigation.html' %}
    </div>

    <!-- Content Area -->
    <div class="col-12 col-lg-9 doc-content-wrapper">
      <div class="doc-content">
        <!-- Breadcrumb -->
        <nav aria-label="breadcrumb" class="mb-4">
          <ol class="breadcrumb">
            <li class="breadcrumb-item">
              <a href="{{ url_for('documentation.index') }}">Documentation</a>
            </li>
            <li class="breadcrumb-item">{{ section_title }}</li>
            <li class="breadcrumb-item active" aria-current="page">{{ page_title }}</li>
          </ol>
        </nav>

        <!-- Page Content -->
        {% block doc_content %}{% endblock %}

        <!-- Previous/Next Navigation -->
        <div class="doc-pagination mt-5 pt-4 border-top">
          <div class="row">
            <div class="col-6">
              {% if prev_page %}
              <a href="{{ url_for('documentation.page', section=prev_page.section, page=prev_page.slug) }}"
                 class="btn btn-outline-secondary">
                ← {{ prev_page.title }}
              </a>
              {% endif %}
            </div>
            <div class="col-6 text-end">
              {% if next_page %}
              <a href="{{ url_for('documentation.page', section=next_page.section, page=next_page.slug) }}"
                 class="btn btn-outline-primary">
                {{ next_page.title }} →
              </a>
              {% endif %}
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>
{% endblock %}
```

#### 1E. Navigation Sidebar

**File:** `containers/backupchecks/src/templates/documentation/_navigation.html`

```html
<nav class="doc-nav">
  <div class="doc-nav-header">
    <h5>📖 Documentation</h5>
  </div>

  {% for section_key, section_data in navigation.structure.items() %}
  <div class="doc-nav-section {% if section_key == navigation.current_section %}active{% endif %}">
    <div class="doc-nav-section-title">
      <span class="doc-nav-icon">{{ section_data.icon }}</span>
      {{ section_data.title }}
    </div>

    <ul class="doc-nav-pages">
      {% for page in section_data.pages %}
      <li class="{% if section_key == navigation.current_section and page.slug == navigation.current_page %}active{% endif %}">
        <a href="{{ url_for('documentation.page', section=section_key, page=page.slug) }}">
          {{ page.title }}
        </a>
      </li>
      {% endfor %}
    </ul>
  </div>
  {% endfor %}
</nav>
```

#### 1F. CSS Styling

**File:** `containers/backupchecks/src/static/css/documentation.css`

```css
/* Documentation Container */
.documentation-container {
  margin-top: 20px;
}

/* Sidebar */
.doc-sidebar-wrapper {
  border-right: 1px solid #dee2e6;
  min-height: calc(100vh - 80px);
}

.doc-nav {
  position: sticky;
  top: 20px;
  padding: 20px;
  max-height: calc(100vh - 100px);
  overflow-y: auto;
}

.doc-nav-header h5 {
  margin-bottom: 20px;
  padding-bottom: 10px;
  border-bottom: 2px solid #007bff;
}

.doc-nav-section {
  margin-bottom: 20px;
}

.doc-nav-section-title {
  font-weight: 600;
  margin-bottom: 10px;
  padding: 8px 12px;
  background-color: #f8f9fa;
  border-radius: 4px;
  cursor: pointer;
}

.doc-nav-section.active .doc-nav-section-title {
  background-color: #e7f1ff;
  color: #0056b3;
}

.doc-nav-icon {
  margin-right: 8px;
}

.doc-nav-pages {
  list-style: none;
  padding-left: 30px;
  margin: 0;
}

.doc-nav-pages li {
  margin: 5px 0;
}

.doc-nav-pages li a {
  display: block;
  padding: 5px 10px;
  color: #495057;
  text-decoration: none;
  border-radius: 4px;
  transition: all 0.2s;
}

.doc-nav-pages li a:hover {
  background-color: #f8f9fa;
  color: #007bff;
}

.doc-nav-pages li.active a {
  background-color: #007bff;
  color: white;
  font-weight: 500;
}

/* Content Area */
.doc-content-wrapper {
  padding: 20px 40px;
}

.doc-content {
  max-width: 900px;
  margin: 0 auto;
}

.doc-content h1 {
  margin-bottom: 30px;
  padding-bottom: 15px;
  border-bottom: 3px solid #007bff;
}

.doc-content h2 {
  margin-top: 40px;
  margin-bottom: 20px;
  color: #0056b3;
}

.doc-content h3 {
  margin-top: 30px;
  margin-bottom: 15px;
}

.doc-content img {
  max-width: 100%;
  height: auto;
  border: 1px solid #dee2e6;
  border-radius: 4px;
  margin: 20px 0;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.doc-content figcaption {
  text-align: center;
  font-style: italic;
  color: #6c757d;
  margin-top: -15px;
  margin-bottom: 20px;
}

/* Code Blocks */
.doc-content pre {
  background-color: #f8f9fa;
  border: 1px solid #dee2e6;
  border-radius: 4px;
  padding: 15px;
  overflow-x: auto;
}

.doc-content code {
  background-color: #f8f9fa;
  padding: 2px 6px;
  border-radius: 3px;
  font-family: 'Courier New', monospace;
  font-size: 0.9em;
}

.doc-content pre code {
  background-color: transparent;
  padding: 0;
}

/* Tables */
.doc-content table {
  width: 100%;
  margin: 20px 0;
  border-collapse: collapse;
}

.doc-content table th,
.doc-content table td {
  padding: 12px;
  border: 1px solid #dee2e6;
  text-align: left;
}

.doc-content table th {
  background-color: #f8f9fa;
  font-weight: 600;
}

.doc-content table tr:nth-child(even) {
  background-color: #f8f9fa;
}

/* Callout Boxes */
.doc-callout {
  padding: 15px 20px;
  margin: 20px 0;
  border-left: 4px solid;
  border-radius: 4px;
}

.doc-callout-info {
  background-color: #e7f3ff;
  border-left-color: #007bff;
}

.doc-callout-warning {
  background-color: #fff3cd;
  border-left-color: #ffc107;
}

.doc-callout-tip {
  background-color: #d4edda;
  border-left-color: #28a745;
}

.doc-callout-danger {
  background-color: #f8d7da;
  border-left-color: #dc3545;
}

.doc-callout strong {
  display: block;
  margin-bottom: 5px;
}

/* Pagination */
.doc-pagination {
  margin-top: 40px;
}

/* Responsive */
@media (max-width: 991px) {
  .doc-sidebar-wrapper {
    border-right: none;
    border-bottom: 1px solid #dee2e6;
    min-height: auto;
  }

  .doc-nav {
    position: static;
    max-height: none;
  }

  .doc-content-wrapper {
    padding: 20px 15px;
  }
}
```

---

## 📝 Content Template Example

**File:** `containers/backupchecks/src/templates/documentation/getting-started/what-is-backupchecks.html`

```html
{% extends "documentation/base.html" %}

{% block doc_content %}
<h1>What is BackupChecks?</h1>

<p class="lead">
  BackupChecks is a backup monitoring and validation system designed to help IT teams
  verify that backups are running successfully across their customer infrastructure.
</p>

<h2>Key Features</h2>

<ul>
  <li><strong>Automated Mail Parsing:</strong> Import backup reports via email and automatically parse results</li>
  <li><strong>Approval Workflow:</strong> Review and approve backup jobs on a daily basis</li>
  <li><strong>Customer Management:</strong> Organize backups by customer and manage multiple backup jobs per customer</li>
  <li><strong>Autotask Integration:</strong> Create tickets in Autotask PSA for failed backups</li>
  <li><strong>Reporting:</strong> Generate backup status reports with flexible scheduling</li>
  <li><strong>Role-Based Access:</strong> Admin, Operator, Reporter, and Viewer roles</li>
</ul>

<figure>
  <img src="{{ url_for('static', filename='images/documentation/dashboard-overview.png') }}"
       alt="BackupChecks Dashboard Overview" />
  <figcaption>Figure 1: BackupChecks Dashboard showing daily backup status</figcaption>
</figure>

<h2>How It Works</h2>

<p>BackupChecks follows a simple workflow:</p>

<ol>
  <li><strong>Import:</strong> Backup reports are sent via email to a configured mailbox</li>
  <li><strong>Parse:</strong> The system parses email content to extract backup status</li>
  <li><strong>Match:</strong> Reports are matched to configured jobs based on sender, subject, and content</li>
  <li><strong>Review:</strong> Operators review backup status and approve successful jobs</li>
  <li><strong>Alert:</strong> Failed backups can trigger Autotask tickets or manual follow-up</li>
  <li><strong>Report:</strong> Generate periodic reports to track backup health over time</li>
</ol>

<div class="doc-callout doc-callout-info">
  <strong>💡 Tip:</strong>
  Start with the <a href="{{ url_for('documentation.page', section='getting-started', page='quick-start') }}">Quick Start Checklist</a>
  to get your first customer and job configured.
</div>

<h2>Who Should Use BackupChecks?</h2>

<p>BackupChecks is designed for:</p>

<ul>
  <li><strong>Managed Service Providers (MSPs):</strong> Monitor backups across multiple customer environments</li>
  <li><strong>IT Departments:</strong> Track backup compliance for internal infrastructure</li>
  <li><strong>Backup Administrators:</strong> Centralize backup verification from multiple backup solutions</li>
</ul>

<h2>Supported Backup Software</h2>

<p>BackupChecks supports parsing backup reports from:</p>

<table>
  <thead>
    <tr>
      <th>Software</th>
      <th>Support Level</th>
      <th>Notes</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Veeam Backup & Replication</td>
      <td>Full</td>
      <td>Email notifications with detailed job status</td>
    </tr>
    <tr>
      <td>Acronis Cyber Protect</td>
      <td>Full</td>
      <td>Backup completion reports</td>
    </tr>
    <tr>
      <td>Synology Active Backup</td>
      <td>Full</td>
      <td>Task result notifications</td>
    </tr>
    <tr>
      <td>Custom/Other</td>
      <td>Configurable</td>
      <td>Manual job configuration for non-standard formats</td>
    </tr>
  </tbody>
</table>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Important:</strong>
  BackupChecks monitors backup <em>reports</em>, not the backup data itself. Ensure your backup software is configured to send email notifications on job completion.
</div>

<h2>Next Steps</h2>

<p>Ready to get started? Continue to:</p>

<ul>
  <li><a href="{{ url_for('documentation.page', section='getting-started', page='first-login') }}">First Login & Dashboard</a> - Learn about the dashboard interface</li>
  <li><a href="{{ url_for('documentation.page', section='getting-started', page='quick-start') }}">Quick Start Checklist</a> - Set up your first customer and job</li>
  <li><a href="{{ url_for('documentation.page', section='mail-import', page='setup') }}">Mail Import Setup</a> - Configure email integration</li>
</ul>

{% endblock %}
```

---

## ✅ Testing Checklist

### Navigation & Routing
- [ ] Navigate to /documentation - redirects to first page
- [ ] Click on sidebar navigation - loads correct page
- [ ] Breadcrumb shows correct hierarchy
- [ ] Previous/Next buttons work correctly
- [ ] Previous button hidden on first page
- [ ] Next button hidden on last page
- [ ] Active page highlighted in sidebar
- [ ] Active section expanded in sidebar

### Access Control
- [ ] Not logged in - redirected to login
- [ ] Logged in as admin - can access all pages
- [ ] Logged in as operator - can access all pages
- [ ] Logged in as viewer - can access all pages
- [ ] Documentation menu item highlighted when active

### Content Rendering
- [ ] All 30+ pages render without errors
- [ ] Images load correctly
- [ ] Screenshots display with proper sizing
- [ ] Code blocks formatted correctly
- [ ] Tables display properly
- [ ] Callout boxes styled correctly
- [ ] Links between pages work
- [ ] External links open in new tab

### Responsive Design
- [ ] Desktop (1920x1080) - sidebar fixed, content readable
- [ ] Laptop (1366x768) - layout works
- [ ] Tablet (768x1024) - sidebar collapses or stacks
- [ ] Mobile (375x667) - content readable, navigation accessible

### Performance
- [ ] Page loads fast (<500ms)
- [ ] Images optimized (screenshots compressed)
- [ ] CSS minified
- [ ] No console errors

---

## 📸 Screenshot Guidelines

### Taking Screenshots
- **Resolution:** 1920x1080 (full HD)
- **Browser:** Chrome/Edge in normal mode (not incognito)
- **Zoom:** 100% (default browser zoom)
- **Format:** PNG (for UI clarity)
- **Compression:** Use tools like TinyPNG to reduce file size
- **Naming:** Descriptive kebab-case (e.g., `customer-list-view.png`)

### Screenshot Checklist
- [ ] Remove sensitive/real customer data (use dummy data)
- [ ] Blur or hide any sensitive information
- [ ] Crop to relevant area (don't include browser chrome unless needed)
- [ ] Add borders/shadows for visual depth (done in CSS)
- [ ] Include captions explaining what's shown

### Required Screenshots (Minimum)
- [ ] Dashboard overview
- [ ] Customer list page
- [ ] Job configuration modal
- [ ] Inbox with unread messages
- [ ] Daily Jobs view
- [ ] Run Checks modal (approve/reject)
- [ ] Settings pages (all tabs)
- [ ] Reports creation page
- [ ] Autotask integration settings

---

## 📋 Content Writing Guidelines

### Style Guide
- **Tone:** Professional but friendly
- **Person:** Second person (you/your, not we/our)
- **Tense:** Present tense for instructions
- **Voice:** Active voice preferred
- **Length:** Concise but complete (aim for scanability)

### Structure
- **H1:** Page title (only one per page)
- **H2:** Major sections
- **H3:** Subsections
- **Lists:** Use for steps, features, options
- **Paragraphs:** Keep short (2-4 sentences max)
- **Callouts:** Use for tips, warnings, important notes

### Example Phrasing
✅ **Good:** "Click the **New Customer** button to add a customer"
❌ **Bad:** "We can add a new customer by clicking on the button"

✅ **Good:** "BackupChecks monitors backup reports via email"
❌ **Bad:** "BackupChecks will monitor the backup reports that are sent via email"

### Callout Usage
- **Info (Blue):** General information, tips, context
- **Warning (Yellow):** Important considerations, limitations
- **Tip (Green):** Best practices, shortcuts, recommendations
- **Danger (Red):** Critical warnings, data loss risks

---

## 🚀 Implementation Phases

### Phase 1: Core Infrastructure ✅ COMPLETE
- [x] Create routes file and blueprint
- [x] Add documentation menu item
- [x] Create base layout template
- [x] Create navigation sidebar template
- [x] Create CSS styling
- [x] Test routing and navigation
- [x] Fix CSS image centering
- [x] Add dark mode support

**Status:** In Progress - documentation audit batches 1-3 completed; remaining: Mail Import re-validation, Troubleshooting pages, Sidebar Layout v2 consistency pass
**Time Spent:** ~4 hours

### Phase 2: Content Pages - Getting Started ✅ COMPLETE
- [x] What is BackupChecks?
- [x] First Login & Dashboard
- [x] Quick Start Checklist
- [x] Take screenshots for Getting Started section

**Status:** In Progress - documentation audit batches 1-3 completed; remaining: Mail Import re-validation, Troubleshooting pages, Sidebar Layout v2 consistency pass
**Time Spent:** ~6 hours

### Phase 3: Content Pages - Core Features ✅ COMPLETE (16 of 16 complete)
- [x] User Management (3 pages) ✅
  - [x] Users & Roles
  - [x] Login & Authentication
  - [x] Profile Settings
- [x] Customers & Jobs (4 pages) ✅
  - [x] Managing Customers
  - [x] Configuring Jobs
  - [x] Approved Jobs
  - [x] Job Schedules
- [x] Mail & Import (4 pages) ✅
  - [x] Mail Import Setup
  - [x] Inbox Management
  - [x] Mail Parsing
  - [x] Auto-Import Configuration
- [x] Backup Review (5 pages) ✅
  - [x] Approving Backups
  - [x] Daily Jobs View
  - [x] Run Checks Modal
  - [x] Overrides & Exceptions
  - [x] Remarks & Tickets
- [x] Take screenshots for core features (10 screenshots added)

**Status:** In Progress - documentation audit batches 1-3 completed; remaining: Mail Import re-validation, Troubleshooting pages, Sidebar Layout v2 consistency pass
**Time Spent:** ~21 hours

### Phase 4: Content Pages - Advanced Features (0/14 pages)
- [ ] Reports (4 pages)
- [ ] Autotask Integration (4 pages)
- [ ] Settings (3 pages)
- [ ] Troubleshooting (3 pages)
- [ ] Take screenshots for advanced features

**Estimated Complexity:** High
**Time Estimate:** 7-10 hours

### Phase 5: Polish & Review
- [ ] Proofread all content
- [ ] Verify all links work
- [ ] Optimize all images
- [ ] Test on different screen sizes
- [ ] Get user feedback

**Estimated Complexity:** Low
**Time Estimate:** 2-4 hours

**Total Estimate:** 24-38 hours of work

---

## 📝 Page Content Outline (Template)

For each page, follow this structure:

```
1. Page Title (H1)
2. Introduction paragraph (what this page covers)
3. Main content sections (H2)
   - Explanatory text
   - Screenshots/images
   - Step-by-step instructions (if applicable)
   - Tables for settings/options (if applicable)
4. Callout boxes (tips, warnings)
5. Related pages / Next steps (end of page)
```

---

## 🎯 Success Criteria

- [ ] All 30+ documentation pages created and accessible
- [ ] Navigation works seamlessly (sidebar + prev/next)
- [ ] All screenshots embedded and displaying correctly
- [ ] Content is clear, accurate, and helpful for new users
- [ ] Pages load quickly (<500ms)
- [ ] Mobile-responsive design works on all screen sizes
- [ ] No broken links or missing images
- [ ] Access restricted to logged-in users only
- [ ] Documentation menu item integrated in navbar

---

## 🔮 Future Enhancements (Post-MVP)

- [ ] **Search functionality:** Full-text search across all pages
- [ ] **Keyboard shortcuts:** Navigate pages with arrow keys
- [ ] **Dark mode:** Theme toggle for documentation
- [ ] **Print stylesheet:** Printer-friendly version
- [ ] **Video tutorials:** Embed short walkthrough videos
- [ ] **Feedback widget:** "Was this helpful?" on each page
- [ ] **Version indicator:** Show app version documentation matches
- [ ] **PDF export:** Export entire documentation as PDF
- [ ] **Changelog page:** Document what's new in each version

---

## 📂 Important Files Summary

```
Backend:
- routes_documentation.py              # NEW: Documentation routes + navigation structure

Templates:
- documentation/base.html              # NEW: Base layout with sidebar
- documentation/_navigation.html       # NEW: Sidebar navigation
- documentation/*//*.html              # NEW: 30+ content pages
- layout/base.html                     # MODIFY: Add Documentation menu item

Static Files:
- static/css/documentation.css         # NEW: Documentation styling
- static/images/documentation/*        # NEW: Screenshots folder

Docs:
- changelog-claude.md                  # UPDATE: Document feature addition
```

---

## 💡 Notes

- **Language:** All content in English (app is not translated)
- **Maintenance:** Content updated via git (no in-app editing)
- **Access:** Login required (@login_required on all routes)
- **Screenshots:** Use dummy/anonymized data only
- **Style:** Professional tone, second person, active voice
- **Structure:** Hierarchical navigation, prev/next pagination
- **Performance:** Optimize images, minify CSS
- **Responsive:** Mobile-friendly sidebar and content