docs(user): add comprehensive average sensor documentation

Expanded user documentation with detailed guidance on average sensors:

1. sensors.md (+182 lines):
   - New 'Average Price Sensors' section with mean vs median explanation
   - 3 real-world automation examples (heat pump, dishwasher, EV charging)
   - Display configuration guide with use-case recommendations

2. configuration.md (+75 lines):
   - New 'Average Sensor Display Settings' section
   - Comparison table of display modes (mean/median/both)
   - Attribute availability details and recorder implications

3. Minor updates to installation.md and versioned docs

Impact: Users can now understand when to use mean vs median and how to
configure display format for their specific automation needs.

docs/user/docs/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for configuration instructions.
+> **Note:** This guide is under construction. For detailed setup instructions, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md).
 
 ## Initial Setup
 
@@ -8,8 +8,77 @@ Coming soon...
 
 ## Configuration Options
 
-Coming soon...
+### Average Sensor Display Settings
 
-## Price Thresholds
+**Location:** Settings → Devices & Services → Tibber Prices → Configure → Step 6
+
+The integration allows you to choose how average price sensors display their values. This setting affects all average sensors (daily, 24h rolling, hourly smoothed, and future forecasts).
+
+#### Display Modes
+
+**Median (Default):**
+- Shows the "middle value" when all prices are sorted
+- **Resistant to extreme spikes** - one expensive hour doesn't skew the result
+- Best for understanding **typical price levels**
+- Example: "What was the typical price today?"
+
+**Arithmetic Mean:**
+- Shows the mathematical average of all prices
+- **Includes effect of spikes** - reflects actual cost if consuming evenly
+- Best for **cost calculations and budgeting**
+- Example: "What was my average cost per kWh today?"
+
+#### Why This Matters
+
+Consider a day with these hourly prices:
+```
+10, 12, 13, 15, 80 ct/kWh
+```
+
+- **Median = 13 ct/kWh** ← "Typical" price (middle value, ignores spike)
+- **Mean = 26 ct/kWh** ← Average cost (spike pulls it up)
+
+The median tells you the price was **typically** around 13 ct/kWh (4 out of 5 hours). The mean tells you if you consumed evenly, your **average cost** was 26 ct/kWh.
+
+#### Automation-Friendly Design
+
+**Both values are always available as attributes**, regardless of your display choice:
+
+```yaml
+# These attributes work regardless of display setting:
+{{ state_attr('sensor.tibber_home_average_price_today', 'price_median') }}
+{{ state_attr('sensor.tibber_home_average_price_today', 'price_mean') }}
+```
+
+This means:
+- ✅ You can change the display anytime without breaking automations
+- ✅ Automations can use both values for different purposes
+- ✅ No need to create template sensors for the "other" value
+
+#### Affected Sensors
+
+This setting applies to:
+- Daily average sensors (today, tomorrow)
+- 24-hour rolling averages (trailing, leading)
+- Hourly smoothed prices (current hour, next hour)
+- Future forecast sensors (next 1h, 2h, 3h, ... 12h)
+
+See the **[Sensors Guide](sensors.md#average-price-sensors)** for detailed examples.
+
+#### Choosing Your Display
+
+**Choose Median if:**
+- 👥 You show prices to users ("What's today like?")
+- 📊 You want dashboard values that represent typical conditions
+- 🎯 You compare price levels across days
+- 🔍 You analyze volatility (comparing typical vs extremes)
+
+**Choose Mean if:**
+- 💰 You calculate costs and budgets
+- 📈 You forecast energy expenses
+- 🧮 You need mathematical accuracy for financial planning
+- 📊 You track actual average costs over time
+
+**Pro Tip:** Most users prefer **Median** for displays (more intuitive), but use `price_mean` attribute in cost calculation automations.
 
 Coming soon...

docs/user/docs/installation.md

@@ -1,6 +1,6 @@
 # Installation
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for installation instructions.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for installation instructions.
 
 ## HACS Installation (Recommended)
 

docs/user/docs/sensors.md

@@ -4,7 +4,7 @@ comments: false
 
 # Sensors
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for available sensors.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for available sensors.
 
 > **Tip:** Many sensors have dynamic icons and colors! See the **[Dynamic Icons Guide](dynamic-icons.md)** and **[Dynamic Icon Colors Guide](icon-colors.md)** to enhance your dashboards.
 
@@ -23,7 +23,185 @@ Both sensors include rich attributes with period details, intervals, relaxation
 
 ## Core Price Sensors
 
-Coming soon...
+### Average Price Sensors
+
+The integration provides several sensors that calculate average electricity prices over different time windows. These sensors show a **typical** price value that represents the overall price level, helping you make informed decisions about when to use electricity.
+
+#### Available Average Sensors
+
+| Sensor | Description | Time Window |
+|--------|-------------|-------------|
+| **Average Price Today** | Typical price for current calendar day | 00:00 - 23:59 today |
+| **Average Price Tomorrow** | Typical price for next calendar day | 00:00 - 23:59 tomorrow |
+| **Trailing Price Average** | Typical price for last 24 hours | Rolling 24h backward |
+| **Leading Price Average** | Typical price for next 24 hours | Rolling 24h forward |
+| **Current Hour Average** | Smoothed price around current time | 5 intervals (~75 min) |
+| **Next Hour Average** | Smoothed price around next hour | 5 intervals (~75 min) |
+| **Next N Hours Average** | Future price forecast | 1h, 2h, 3h, 4h, 5h, 6h, 8h, 12h |
+
+#### Configurable Display: Median vs Mean
+
+All average sensors support **two different calculation methods** for the state value:
+
+- **Median** (default): The "middle value" when all prices are sorted. Resistant to extreme price spikes, shows the **typical** price level you experienced.
+- **Arithmetic Mean**: The mathematical average including all prices. Better for **cost calculations** but affected by extreme spikes.
+
+**Why two values matter:**
+
+```yaml
+# Example price data for one day:
+# Prices: 10, 12, 13, 15, 80 ct/kWh (one extreme spike)
+#
+# Median = 13 ct/kWh    ← "Typical" price level (middle value)
+# Mean = 26 ct/kWh      ← Mathematical average (affected by spike)
+```
+
+The median shows you what price level was **typical** during that period, while the mean shows the actual **average cost** if you consumed evenly throughout the period.
+
+#### Configuring the Display
+
+You can choose which value is displayed in the sensor state:
+
+1. Go to **Settings → Devices & Services → Tibber Prices**
+2. Click **Configure** on your home
+3. Navigate to **Step 6: Average Sensor Display Settings**
+4. Choose between:
+   - **Median** (default) - Shows typical price level, resistant to spikes
+   - **Arithmetic Mean** - Shows actual mathematical average
+
+**Important:** Both values are **always available** as sensor attributes, regardless of your choice! This ensures your automations continue to work if you change the display setting.
+
+#### Using Both Values in Automations
+
+Both `price_mean` and `price_median` are always available as attributes:
+
+```yaml
+# Example: Get both values regardless of display setting
+sensor:
+  - platform: template
+    sensors:
+      daily_price_analysis:
+        friendly_name: "Daily Price Analysis"
+        value_template: >
+          {% set median = state_attr('sensor.tibber_home_average_price_today', 'price_median') %}
+          {% set mean = state_attr('sensor.tibber_home_average_price_today', 'price_mean') %}
+          {% set current = states('sensor.tibber_home_current_interval_price') | float %}
+
+          {% if current < median %}
+            Below typical ({{ ((1 - current/median) * 100) | round(1) }}% cheaper)
+          {% elif current < mean %}
+            Typical price range
+          {% else %}
+            Above average ({{ ((current/mean - 1) * 100) | round(1) }}% more expensive)
+          {% endif %}
+```
+
+#### Practical Examples
+
+**Example 1: Smart dishwasher control**
+
+Run dishwasher only when price is significantly below the daily typical level:
+
+```yaml
+automation:
+  - alias: "Start Dishwasher When Cheap"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.tibber_home_best_price_period
+        to: "on"
+    condition:
+      # Only if current price is at least 20% below typical (median)
+      - condition: template
+        value_template: >
+          {% set current = states('sensor.tibber_home_current_interval_price') | float %}
+          {% set median = state_attr('sensor.tibber_home_average_price_today', 'price_median') | float %}
+          {{ current < (median * 0.8) }}
+    action:
+      - service: switch.turn_on
+        entity_id: switch.dishwasher
+```
+
+**Example 2: Cost-aware heating control**
+
+Use mean for actual cost calculations:
+
+```yaml
+automation:
+  - alias: "Heating Budget Control"
+    trigger:
+      - platform: time
+        at: "06:00:00"
+    action:
+      # Calculate expected daily heating cost
+      - variables:
+          mean_price: "{{ state_attr('sensor.tibber_home_average_price_today', 'price_mean') | float }}"
+          heating_kwh_per_day: 15  # Estimated consumption
+          daily_cost: "{{ (mean_price * heating_kwh_per_day / 100) | round(2) }}"
+      - service: notify.mobile_app
+        data:
+          title: "Heating Cost Estimate"
+          message: "Expected cost today: €{{ daily_cost }} (avg price: {{ mean_price }} ct/kWh)"
+```
+
+**Example 3: Smart charging based on rolling average**
+
+Use trailing average to understand recent price trends:
+
+```yaml
+automation:
+  - alias: "EV Charging - Price Trend Based"
+    trigger:
+      - platform: state
+        entity_id: sensor.ev_battery_level
+    condition:
+      # Start charging if current price < 90% of recent 24h average
+      - condition: template
+        value_template: >
+          {% set current = states('sensor.tibber_home_current_interval_price') | float %}
+          {% set trailing_avg = state_attr('sensor.tibber_home_trailing_price_average', 'price_median') | float %}
+          {{ current < (trailing_avg * 0.9) }}
+      # And battery < 80%
+      - condition: numeric_state
+        entity_id: sensor.ev_battery_level
+        below: 80
+    action:
+      - service: switch.turn_on
+        entity_id: switch.ev_charger
+```
+
+#### Key Attributes
+
+All average sensors provide these attributes:
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `price_mean` | Arithmetic mean (always available) | 25.3 ct/kWh |
+| `price_median` | Median value (always available) | 22.1 ct/kWh |
+| `interval_count` | Number of intervals included | 96 |
+| `timestamp` | Reference time for calculation | 2025-12-18T00:00:00+01:00 |
+
+**Note:** The `price_mean` and `price_median` attributes are **always present** regardless of which value you configured for display. This ensures automation compatibility when changing the display setting.
+
+#### When to Use Which Value
+
+**Use Median for:**
+- ✅ Comparing "typical" price levels across days
+- ✅ Determining if current price is unusually high/low
+- ✅ User-facing displays ("What was today like?")
+- ✅ Volatility analysis (comparing typical vs extremes)
+
+**Use Mean for:**
+- ✅ Cost calculations and budgeting
+- ✅ Energy cost estimations
+- ✅ Comparing actual average costs between periods
+- ✅ Financial planning and forecasting
+
+**Both values tell different stories:**
+- High median + much higher mean = Expensive spikes occurred
+- Low median + higher mean = Generally cheap with occasional spikes
+- Similar median and mean = Stable prices (low volatility)
+
+
 
 ## Statistical Sensors
 

docs/user/versioned_docs/version-v0.21.0/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for configuration instructions.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for configuration instructions.
 
 ## Initial Setup
 

docs/user/versioned_docs/version-v0.21.0/installation.md

@@ -1,6 +1,6 @@
 # Installation
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for installation instructions.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for installation instructions.
 
 ## HACS Installation (Recommended)
 

docs/user/versioned_docs/version-v0.21.0/sensors.md

@@ -4,7 +4,7 @@ comments: false
 
 # Sensors
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for available sensors.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for available sensors.
 
 > **Tip:** Many sensors have dynamic icons and colors! See the **[Dynamic Icons Guide](dynamic-icons.md)** and **[Dynamic Icon Colors Guide](icon-colors.md)** to enhance your dashboards.
 

docs/user/versioned_docs/version-v0.22.0/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for configuration instructions.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for configuration instructions.
 
 ## Initial Setup
 

docs/user/versioned_docs/version-v0.22.0/installation.md

@@ -1,6 +1,6 @@
 # Installation
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for installation instructions.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for installation instructions.
 
 ## HACS Installation (Recommended)
 

docs/user/versioned_docs/version-v0.22.0/sensors.md

@@ -4,7 +4,7 @@ comments: false
 
 # Sensors
 
-> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for available sensors.
+> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for available sensors.
 
 > **Tip:** Many sensors have dynamic icons and colors! See the **[Dynamic Icons Guide](dynamic-icons.md)** and **[Dynamic Icon Colors Guide](icon-colors.md)** to enhance your dashboards.