config.yaml.example

# Configuration for HA to BookStack Documentation Generator
# Copy this file to config.yaml and fill in your details.
# DO NOT commit config.yaml to version control — it contains API tokens.
# Recommended: chmod 600 config.yaml

# ============================================================================
# BOOKSTACK CONNECTION
# ============================================================================
bookstack:
  url: "http://YOUR_BOOKSTACK_IP:PORT/"
  token_id: "YOUR_BOOKSTACK_TOKEN_ID"
  token_secret: "YOUR_BOOKSTACK_TOKEN_SECRET"

  # Book name — will be auto-created if it doesn't exist
  book_name: "Home Assistant Documentation"

  # Book ID — leave null on first run; the script finds or creates the book
  # automatically. You can set this after first run to skip the name lookup.
  book_id: null

  # Chapter IDs for page organization (leave null to place all pages at book
  # level). Set after creating chapters manually in BookStack if desired.
  chapters:
    overview: null
    inventory: null
    integrations: null
    automations: null
    infrastructure: null
    software: null
    reference: null

# ============================================================================
# HOME ASSISTANT CONNECTION
# ============================================================================
homeassistant:
  url: "http://homeassistant.local:8123"
  token: "YOUR_HA_LONG_LIVED_ACCESS_TOKEN"
  # Generate a token at: HA → Profile → Long-Lived Access Tokens

# ============================================================================
# DOCUMENTATION OPTIONS
# ============================================================================
documentation:
  # Include HTML styling in markdown output.
  # Requires BookStack custom CSS — see README for installation instructions.
  # Use --no-style flag or set false here for plain markdown output.
  styled_output: true

  # Which sections to generate (set false to skip any section)
  sections:
    system_overview: true
    entity_inventory: true
    integration_quirks: true
    automation_summary: true
    quick_reference: true

  # Entity inventory options
  inventory:
    include_unavailable: true
    max_entities_per_section: 100

# ============================================================================
# SYSTEM-SPECIFIC INFORMATION
# ============================================================================
system_info:
  location_name: "Home"
  timezone: "America/New_York"   # IANA format, e.g. America/Chicago

  coordinators:
    zigbee:
      type: "Zigbee2MQTT"        # or "ZHA"
      hardware: "Your coordinator hardware description"
      location: "Where it's physically installed"
      notes: >
        Any relevant notes about placement, coverage, or migration history.

    zwave:
      enabled: false             # Set true if you have Z-Wave
      type: "Z-Wave JS"
      hardware: "Your Z-Wave hardware"
      notes: "What devices it controls"

  network:
    router_brand: "Your router brand"
    router_model: "Your router model"
    subnet: "192.168.1.0/24"
    lan_ip: "192.168.1.1"
    ha_ip: "192.168.1.x"

    # DNS architecture — documents your DNS tier setup
    dns:
      primary:
        host: "hostname"
        ip: "192.168.1.x"
        software: "AdGuard Home"   # or Pi-hole, etc.
        notes: "Always-on; survives HA reboots"
      secondary:
        host: "homeassistant"
        ip: "192.168.1.x"
        software: "AdGuard Home (HA add-on)"
        notes: "Fallback when primary is unavailable"
      tertiary:
        host: "Router"
        ip: "192.168.1.1"
        notes: "Last resort, no filtering"
      dhcp_dns_assignment:
        dns1: "192.168.1.x"
        dns2: "192.168.1.x"

    wan:
      fios_router_ip: "192.168.0.1"

  # Optional: document Proxmox or other hypervisor details
  proxmox:
    host_ip: "192.168.1.x"
    ram_total: "16GB"
    ram_allocated_to_ha: "8GB"
    notes: "HA runs as a VM. Proxmox reboots are DNS-safe if primary DNS is on separate hardware."

  household_members:
    - name: "Primary User"
      role: "Administrator"
      devices: "iPhone"
    - name: "Another User"
      devices: "iPhone"
    # Add more as needed. 'notes' field optional, e.g.:
    # - name: "Remote User"
    #   devices: "iPhone"
    #   notes: "Frequently away"

# ============================================================================
# ADDITIONAL INTEGRATIONS
# Documents integrations not captured automatically by entity pattern matching.
# ============================================================================
additional_integrations:
  - name: "ESPHome Devices"
    devices:
      - name: "Sensor Name"
        notes: "What it does"

  - name: "Stormglass"
    notes: "Marine/tide data sensors"

  # Add any others you want documented in Software & Integrations

# ============================================================================
# INTEGRATION-SPECIFIC QUIRKS & SOLUTIONS
# Populates the "Known Issues & Quirks" page in BookStack.
# Severity levels: low, medium, high, critical
# ============================================================================
quirks:
  - integration: "Bond"
    severity: "medium"
    title: "RF devices lose state tracking when physical remotes are used"
    description: >
      Bond uses one-way RF communication. HA sends commands but cannot detect
      physical remote button presses, causing state drift over time.
    affected_devices:
      - "Living Room Fan (fan.living_room)"
      - "Bedroom Fan (fan.bedroom)"
    workaround: >
      Create a daily automation (e.g. 4 AM) to reset all Bond device states.
      Long-term fix: install inline switches (e.g. Sonoff ZBMINIR2 in detached
      relay mode) to route physical presses through HA, maintaining state accuracy.
    notes: "Inline switch solution prevents drift entirely once deployed"

  # More examples:
  # - integration: "Ring"
  #   severity: "low"
  #   title: "Cloud-dependent — 30-60s motion detection latency"
  #   description: >
  #     Ring requires internet to function. Motion events have significant delay.
  #   notes: "Consider local camera alternatives for time-sensitive automations"

# ============================================================================
# EXCLUSIONS
# Entities matching these patterns are excluded from the Entity Inventory.
# Uses Python regex matched against entity_id.
# ============================================================================
exclusions:
  patterns:
    - "sensor.*_next_alarm$"
    - "sensor.*_next_timer$"
    - "sensor.*_next_reminder$"
    - "sensor.*_rssi$"
    - "sensor.*_notification_power_management_.*"
    - "sensor.*_floors_ascended$"
    - "sensor.*_floors_descended$"
    - "sensor.*_average_active_pace$"
    - "sensor.*_steps$"
    - "sensor.*_scene_state_.*"

  # Entire domains to exclude (e.g. ["tts", "stt", "wake_word"])
  domains: []

  # Specific entity IDs to exclude
  entities: []

  # Areas to exclude
  areas: []