versioned_docs/ was already tracked but versioned_sidebars/ was never
committed. Docusaurus requires both to render sidebar navigation for
old versions — without the sidebar files, all versioned pages show
no navigation.
Adds sidebar snapshots for user and developer docs:
v0.21.0, v0.22.0, v0.22.1, v0.23.0, v0.23.1, v0.24.0, v0.27.0, v0.28.0
Future versions: CI (docusaurus.yml) runs docs:version on each stable
tag push, which generates both versioned_docs/ and versioned_sidebars/.
The workflow should be updated to commit these files back, or they need
to be added manually after each release.
Impact: Sidebar navigation now appears correctly for all existing
versioned documentation pages.
Swizzled @docusaurus/theme-mermaid's Mermaid component to wrap
every diagram with a portal-based lightbox overlay.
An expand icon appears on diagram hover. Clicking opens the SVG
in a full-screen overlay (90vw × 85vh, scrollable). Closes via
backdrop click, Escape key, or close button. SSR-safe, no
external dependencies. Matches Tibber electric color theme.
Impact: Users can inspect complex flowcharts (e.g. the Options
Flow wizard) without squinting at small embedded diagrams.
Switched Giscus mapping from 'pathname' to 'og:title' with strict=1.
Discussions are now titled after the readable page title (e.g.
'Chart Examples | Tibber Prices Integration') instead of the URL path,
making them immediately identifiable in the GitHub Discussions list.
Added a small hint above every comment box pointing users to open
a dedicated Discussion on GitHub for new questions/ideas, so
page-specific comments don't accumulate unrelated threads.
Note: Existing Discussion #94 (pathname-mapped) will no longer appear
on chart-examples — a new og:title-mapped discussion will be created
on the next comment. #94 remains visible on GitHub.
Impact: Maintainer can identify discussion origin at a glance.
Users are guided toward proper Discussion threads for new topics.
Added a dedicated 'Finding Your Entry ID' section to actions.md
explaining the two workflows: dropdown in the Action UI vs.
'Copy Config Entry ID' from the integration's three-dot menu in YAML.
Added matching :::info callouts to chart-examples.md and
automation-examples.md where entry_id: YOUR_ENTRY_ID appears in code
examples, and a new 'Config Entry ID' entry in the glossary.
Addresses user confusion reported in GitHub Discussions #94.
Impact: Users no longer get stuck on YOUR_ENTRY_ID placeholders.
Both GUI and YAML workflows are clearly explained at the point of need.
Add coverage for the state_class/statistics table optimization across
both user and developer documentation.
docs/user/docs/configuration.md:
- Add 'Price Sensor Statistics' section explaining that only 3 sensors
write to the HA statistics database (current_interval_price,
current_interval_price_base, average_price_today)
- Fix incorrect entity ID examples: remove non-existent _override suffix
from recorder exclude globs, Developer Tools example, and seasonal
automation example (actual IDs: number.*_best_price_flexibility etc.)
docs/developer/docs/recorder-optimization.md:
- Add 'Long-Term Statistics Optimization (state_class)' section covering
the statistics/statistics_short_term table dimension, which is distinct
from _unrecorded_attributes (state_attributes table)
- Documents the MONETARY device_class constraint (MEASUREMENT blocked by
hassfest, only TOTAL or None valid), the 3 sensors keeping TOTAL with
rationale, the 23 sensors set to None, and ~88% write reduction
- Includes comparison table: _unrecorded_attributes vs state_class
Impact: Users now understand the built-in statistics optimization and
have correct recorder exclude examples. Developers understand both
optimization layers and their interaction.
User docs (period-calculation.md):
- New troubleshooting section "Fewer Periods Than Configured" (most
common confusing scenario, added before "No Periods Found")
- Extended "Understanding Sensor Attributes" section: all four diagnostic
attributes documented with concrete YAML examples and prose explanations
- Updated Table of Contents
Developer docs (period-calculation-theory.md):
- New section "Flat Day and Low-Price Adaptations" (between Flex Limits
and Relaxation Strategy) documenting all three mechanisms with
implementation details, scaling tables, and rationale for hardcoding
- Two new scenarios: 2b (flat day with adaptive min_periods) and 2c
(solar surplus / absolute low-price day) with expected logs and
sensor attribute examples
- Debugging checklist point 6: flat day / low-price checks with
exact log string patterns to grep for
- Diagnostic attribute reference table in the debugging section
Impact: Users can self-diagnose "fewer periods than configured" without
support. Contributors understand why the three thresholds are hardcoded
and cannot be user-configured.
Add calculation summary attributes to best_price_period and
peak_price_period binary sensors for diagnostic transparency.
New attributes (all excluded from recorder history):
- min_periods_configured: User's configured target per day (always shown)
- periods_found_total: Actual periods found across all days (always shown)
- flat_days_detected: Days where CV <= 10% reduced target to 1 (only when > 0)
- relaxation_incomplete: Some days couldn't reach the target (only when true)
These attributes explain observed behavior without requiring users to
read logs: seeing "flat_days_detected: 1" alongside
"min_periods_configured: 2, periods_found_total: 1" immediately
explains why the count is lower than configured on uniform-price days.
Implementation:
- _compute_day_effective_min() now returns (dict, int) tuple to propagate
the flat day count through to the metadata dict
- flat_days_detected added to metadata["relaxation"] in
calculate_periods_with_relaxation()
- build_final_attributes_simple() gains optional period_metadata parameter
- New add_calculation_summary_attributes() function handles the rendering
- Attributes are shown even when no period is currently active
Updated recorder-optimization.md: attribute counts + clarified that
timestamp is correctly excluded (entity native_value is recorded
separately by HA as the entity state itself).
Impact: Users can understand why they received fewer periods than
configured without enabling debug logging.
When runtime config override entities (number/switch) are enabled,
the Options Flow now displays warning indicators at the top of each
affected section. Users see which fields are being managed by config
entities and can still edit the base values if needed.
Changes:
- Add ConstantSelector warnings in Best Price/Peak Price sections
- Implement multi-language support for override warnings (de, en, nb, nl, sv)
- Add _get_override_translations() to load translated field labels
- Add _get_active_overrides() to detect enabled override entities
- Extend get_best_price_schema/get_peak_price_schema with translations param
- Add 14 number/switch config entities for runtime period tuning
- Document runtime configuration entities in user docs
Warning format adapts to overridden fields:
- Single: "⚠️ Flexibility controlled by config entity"
- Multiple: "⚠️ Flexibility and Minimum Distance controlled by config entity"
Impact: Users can now dynamically adjust period calculation parameters
via Home Assistant automations, scripts, or dashboards without entering
the Options Flow. Clear UI indicators show which settings are currently
overridden.
Added a consistent "Entity ID tip" block and normalized all example
entity IDs to the `<home_name>` placeholder across user docs. Updated
YAML and example references to current entity naming (e.g.,
`sensor.<home_name>_current_electricity_price`,
`sensor.<home_name>_price_today`,
`sensor.<home_name>_today_s_price_volatility`,
`binary_sensor.<home_name>_best_price_period`, etc.). Refreshed
automation examples to use language-independent attributes (e.g.
`price_volatility`) and improved robustness. Aligned ApexCharts examples
to use `sensor.<home_name>_chart_metadata` and corrected references for
tomorrow data availability.
Changed files:
- docs/user/docs/actions.md
- docs/user/docs/automation-examples.md
- docs/user/docs/chart-examples.md
- docs/user/docs/configuration.md
- docs/user/docs/dashboard-examples.md
- docs/user/docs/dynamic-icons.md
- docs/user/docs/faq.md
- docs/user/docs/icon-colors.md
- docs/user/docs/period-calculation.md
- docs/user/docs/sensors.md
Impact: Clearer, language-independent examples that reduce confusion and
prevent brittle automations; easier copy/paste adaptation across setups;
more accurate guidance for chart configuration and period/volatility usage.
Changed all documentation links from version-specific tags (v0.20.0) to
main branch references. This makes documentation maintenance-free - links
stay current as code evolves.
Updated 38 files across:
- docs/developer/docs/ (7 files)
- docs/developer/versioned_docs/version-v0.21.0/ (8 files)
- docs/developer/versioned_docs/version-v0.22.0/ (8 files)
Impact: Documentation links no longer break when new versions are released.
Links always point to current code implementation.
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.
Add user-configurable option to choose between median and arithmetic mean
as the displayed value for all 14 average price sensors, with the alternate
value exposed as attribute.
BREAKING CHANGE: Average sensor default changed from arithmetic mean to
median. Users who rely on arithmetic mean behavior may use the price_mean attribue now, or must manually reconfigure
via Settings → Devices & Services → Tibber Prices → Configure → General
Settings → "Average Sensor Display" → Select "Arithmetic Mean" to get this as sensor state.
Affected sensors (14 total):
- Daily averages: average_price_today, average_price_tomorrow
- 24h windows: trailing_price_average, leading_price_average
- Rolling hour: current_hour_average_price, next_hour_average_price
- Future forecasts: next_avg_3h, next_avg_6h, next_avg_9h, next_avg_12h
Implementation:
- All average calculators now return (mean, median) tuples
- User preference controls which value appears in sensor state
- Alternate value automatically added to attributes
- Period statistics (best_price/peak_price) extended with both values
Technical changes:
- New config option: CONF_AVERAGE_SENSOR_DISPLAY (default: "median")
- Calculator functions return tuples: (avg, median)
- Attribute builders: add_alternate_average_attribute() helper function
- Period statistics: price_avg → price_mean + price_median
- Translations: Updated all 5 languages (de, en, nb, nl, sv)
- Documentation: AGENTS.md, period-calculation.md, recorder-optimization.md
Migration path:
Users can switch back to arithmetic mean via:
Settings → Integrations → Tibber Prices → Configure
→ General Settings → "Average Sensor Display" → "Arithmetic Mean"
Impact: Median is more resistant to price spikes, providing more stable
automation triggers. Statistical analysis from coordinator still uses
arithmetic mean (e.g., trailing_avg_24h for rating calculations).
Co-developed-with: GitHub Copilot <copilot@github.com>
Add repair notification system with three auto-clearing repair types:
- Tomorrow data missing (after 18:00)
- API rate limit exceeded (3+ consecutive errors)
- Home not found in Tibber account
Includes:
- coordinator/repairs.py: Complete TibberPricesRepairManager implementation
- Enhanced API error handling with explicit 5xx handling
- Translations for 5 languages (EN, DE, NB, NL, SV)
- Developer documentation in docs/developer/docs/repairs-system.md
Impact: Users receive actionable notifications for important issues instead
of only seeing stale data in logs.
Update all references to reflect two separate Docusaurus instances
(user + developer) with proper file paths and navigation management.
Changes:
- AGENTS.md: Document Docusaurus structure and file organization
- CONTRIBUTING.md: Add Docusaurus workflow guidelines
- docs/developer/docs/period-calculation-theory.md: Fix cross-reference
- docs/developer/sidebars.ts: Add recorder-optimization to navigation
Documentation organized as:
- docs/user/docs/*.md (user guides, via sidebars.ts)
- docs/developer/docs/*.md (developer guides, via sidebars.ts)
- AGENTS.md (AI patterns, conventions)
Impact: AI and contributors know where to place new documentation.
Add comprehensive documentation for _unrecorded_attributes
implementation, categorizing all excluded attributes with reasoning,
expected database impact, and decision framework for future attributes.
Added to Developer Docs → Advanced Topics navigation.
Content includes:
- 7 exclusion categories with examples
- Space savings calculations (60-85% reduction)
- Decision framework for new attributes
- Testing and validation guidelines
- SQL queries for verification
