docs(actions): mark scheduling actions and plan_charging as experimental

Add warnings to indicate that scheduling actions and the plan_charging action are experimental and subject to change. This informs users to use them with caution and report any issues.

Impact: Users are aware of the experimental nature of these features, promoting careful usage.

docs/user/docs/actions.md

@@ -32,6 +32,10 @@ If you have configured more than one Tibber home, each home has its own config e
 
 ### Scheduling Actions
 
+:::warning Experimental
+The scheduling actions and `plan_charging` are **experimental** and still undergoing testing. Their parameters and response formats may change in future releases. Use them with care and [report issues](https://github.com/jpawlowski/hass.tibber_prices/issues).
+:::
+
 Find the cheapest (or most expensive) time windows for your appliances. Ideal for automating when to run devices based on real price data.
 
 | Action | Description | Best For |

docs/user/docs/chart-actions.md

@@ -68,6 +68,7 @@ response_variable: chart_data
 | `day`            | Days to include: yesterday, today, tomorrow | `["today", "tomorrow"]` |
 | `output_format`  | `array_of_objects` or `array_of_arrays`     | `array_of_objects`      |
 | `resolution`     | `interval` (15-min) or `hourly`             | `interval`              |
+| `price_source`   | Primary price series: `total`, `energy`, or `tax` | `total`           |
 | `subunit_currency` | Override display mode: `true` for subunit (ct/øre), `false` for base (€/kr) | Integration setting |
 | `round_decimals` | Decimal places (0-10)                       | 2 (subunit) or 4 (base) |
 
@@ -135,6 +136,39 @@ data:
 
 For detailed parameter descriptions, open **Developer Tools → Actions** and select `tibber_prices.get_chartdata`. The inline documentation is stored in `services.yaml` because actions are backed by services.
 
+### Price Source (`price_source`)
+
+By default, charts use the **total** price (energy + taxes + fees) as the main price series. With `price_source` you can switch the **primary** value to a single component instead:
+
+| Value | Main price series |
+|-------|-------------------|
+| `total` (default) | Full price including energy, taxes, and fees |
+| `energy` | Raw spot/energy price only (excluding taxes and fees) |
+| `tax` | Tax and fee component only |
+
+<details>
+<summary>Show YAML: Chart based on the raw energy price</summary>
+
+```yaml
+service: tibber_prices.get_chartdata
+data:
+    entry_id: YOUR_CONFIG_ENTRY_ID
+    day: ["today", "tomorrow"]
+    price_source: energy # main price = spot price only
+response_variable: chart_data
+```
+
+</details>
+
+:::tip `price_source` vs. `include_energy` / `include_tax`
+These solve different problems:
+
+- **`price_source`** changes *which* component becomes the **main** price value (one series).
+- **`include_energy` / `include_tax`** (see below) keep the total price as main value but **add extra fields** so you can show energy and tax **alongside** the total in the same chart.
+:::
+
+This parameter also applies to [`get_apexcharts_yaml`](#tibber_pricesget_apexcharts_yaml).
+
 ### Energy & Tax Fields
 
 You can include the raw energy price (spot price) and/or tax component in chart data output. This is useful for visualizing how the total price is composed over time, or for feed-in calculations.
@@ -291,6 +325,10 @@ card:
 - **`rating_level`** (default): 3 series (LOW, NORMAL, HIGH) - based on your personal thresholds
 - **`level`**: 5 series (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) - absolute price ranges
 
+**Price Source Option:**
+
+Like `get_chartdata`, this action accepts a `price_source` parameter (`total`, `energy`, or `tax`) to choose which price component the generated chart plots. Defaults to `total`. See [Price Source](#price-source-price_source) above for details.
+
 **Best Price Period Highlights:**
 
 When `highlight_best_price: true`:

docs/user/docs/concepts.md

@@ -97,7 +97,7 @@ Both shapes are reported as **`valley`** by the [Day Pattern sensor](sensors-pri
 
 **Why this matters:** On these days, the Best Price Period may be short (1–2 hours, covering only the absolute minimum), but prices can remain favorable for 4–6 hours. By combining [trend sensors](sensors-trends.md) with [price levels](sensors-ratings-levels.md) in automations, you can ride the full cheap wave instead of only using the detected period.
 
-See [Automation Examples → V-Shaped Days](automation-examples.md#understanding-v-shaped-price-days) for practical patterns.
+See [Automation Examples → Heat Pump Smart Boost](automation-examples.md#heat-pump-smart-boost-with-trend-awareness) for practical patterns.
 
 ## Multi-Home Support
 

docs/user/docs/period-calculation.md

@@ -96,7 +96,7 @@ A Best Price Period is the **cheapest contiguous block** of time — a stretch o
 
 On a V-shaped day (prices drop sharply to a minimum, then rise again), the period therefore starts **at** the low point, not before it — because the intervals leading up to the minimum did not yet meet the price criteria. Only the intervals near the bottom of the V qualify as a coherent cheap block.
 
-**For flexible loads** (e.g., heat pump, battery charging): you can easily ride the full cheap wave by combining the period sensor with the price level and trend sensors. See [V-Shaped Price Days in Automation Examples](./automation-examples.md#understanding-v-shaped-price-days).
+**For flexible loads** (e.g., heat pump, battery charging): you can easily ride the full cheap wave by combining the period sensor with the price level and trend sensors. See [Heat Pump Smart Boost in Automation Examples](./automation-examples.md#heat-pump-smart-boost-with-trend-awareness).
 :::
 
 ### Algorithm Overview
@@ -586,7 +586,7 @@ As described in [Phase 6](#phase-6-relaxation-adaptive), relaxation automaticall
 ## Common Scenarios
 
 :::tip V-shaped price days
-On days with a sharp price dip (e.g. solar midday surplus), the Best Price Period covers only the absolute minimum. The surrounding cheap hours are intentional — the integration shows you the cheapest contiguous block, not a fixed-length window centered on the minimum. To run a device during the full cheap window, see [Understanding V-Shaped Price Days](./automation-examples.md#understanding-v-shaped-price-days) in the Automation Examples.
+On days with a sharp price dip (e.g. solar midday surplus), the Best Price Period covers only the absolute minimum. The surrounding cheap hours are intentional — the integration shows you the cheapest contiguous block, not a fixed-length window centered on the minimum. To run a device during the full cheap window, see [Heat Pump Smart Boost](./automation-examples.md#heat-pump-smart-boost-with-trend-awareness) in the Automation Examples.
 :::
 
 ### Scenario 1: Simple Best Price (Default)

docs/user/docs/plan-charging-action.md

@@ -2,6 +2,10 @@
 
 The `plan_charging` action turns **battery parameters** into a complete **cost-minimized charging schedule**. Instead of manually computing energy, duration, and power, you describe the battery (capacity, current SoC, target SoC, max power) and the action returns a per-interval plan with SoC progression, cost totals, and segment grouping.
 
+:::warning Experimental
+The `plan_charging` action is **experimental** and still undergoing testing. Its parameters, response format, and behavior may change in future releases. Use it in automations with care, and please [report any issues](https://github.com/jpawlowski/hass.tibber_prices/issues).
+:::
+
 :::tip When to use this
 If you already know the duration in minutes and just need the cheapest time window, use [`find_cheapest_hours`](scheduling-actions.md#find-cheapest-hours) or [`find_cheapest_block`](scheduling-actions.md#find-cheapest-block). Use `plan_charging` when you know your battery/EV parameters and want the integration to compute the duration, account for charging losses, and produce a SoC progression.
 :::

docs/user/docs/scheduling-actions.md

@@ -2,6 +2,10 @@
 
 Find the cheapest (or most expensive) time windows for your appliances — automatically. These actions analyze real Tibber price data and return optimal scheduling recommendations.
 
+:::warning Experimental
+The scheduling actions (`find_cheapest_block`, `find_cheapest_hours`, `find_cheapest_schedule`, `find_most_expensive_block`, `find_most_expensive_hours`) are **experimental** and still undergoing testing. Their parameters, response formats, and behavior may change in future releases. Use them in automations with care, and please [report any issues](https://github.com/jpawlowski/hass.tibber_prices/issues).
+:::
+
 :::tip Entity ID tip
 `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
 :::