Audience: automation builders, dashboard authors, and developer-mode users.

This reference focuses on the two most important chore entities:

• sensor.<kid>_kidschores_chores (translation key: kid_chores_sensor)
• sensor.<kid>_kidschores_chore_status_<chore> (translation key: kid_chore_status_sensor)

Both are Home Assistant native entities. Entity IDs and display names are auto-generated, can vary by locale/naming rules, and users can rename entities as needed.

• Entity IDs are now generated by Home Assistant native naming rules and are created with names in local language
• Names can differ across installations and can be renamed by users.
• Stable contract for automations is the exposed state/attribute surface (for example can_claim, can_approve, claim_button_eid, approve_button_eid, disapprove_button_eid) rather than assumed naming patterns.

Example IDs you may see now:

• sensor.john_kidschores_chores
• sensor.henry_kidschores_chore_status_brush_teeth_am
• button.henry_kidschores_disapprove_chore_brush_teeth_am

Aggregated chore statistics for one kid (today/week/month/year/all-time + snapshot counters).

• Native state is the all-time approved count used as the sensor value.

• Identity: purpose, kid_name
• Stats are exposed with chore_stat_ prefix

High-value attribute groups:

• Current snapshot: chore_stat_current_due_today, chore_stat_current_claimed, chore_stat_current_approved, chore_stat_current_overdue
• Today/Week/Month/Year totals: approved, claimed, missed, completed, points
• All-time totals: approved_all_time, claimed_all_time, missed_all_time, completed_all_time, points_all_time
• Streaks: chore_stat_longest_streak, chore_stat_longest_missed_streak
• Averages: chore_stat_avg_per_day_week, chore_stat_avg_per_day_month, chore_stat_avg_per_day_year
• Top chores: chore_stat_top_chores_week, chore_stat_top_chores_month, chore_stat_top_chores_year

These map to the rich dashboard rows such as:

• Current Due Today / Current Claimed / Current Approved / Current Overdue
• Approved/Claimed/Missed/Completed/Points across time windows
• Average Per Day (Week/Month/Year)
• Top Chore (Week/Month/Year)

One sensor per kid+chore pair with lifecycle state, timing context, actionable flags, and per-chore performance stats.

Operational values include:

• pending, due, claimed, approved, overdue
• waiting, not_my_turn, missed, completed_by_other
• claimed_in_part, approved_in_part (group/global contexts)

Identity and metadata:

• purpose, kid_name, chore_name, description, assigned_kids, labels

Configuration snapshot:

• default_points, completion_criteria, approval_reset_type, recurring_frequency, applicable_days

Time and availability context:

• due_date, due_window_start, available_at, time_until_due, time_until_overdue, approval_period_start
• Rotation/locks: global_state, lock_reason, turn_kid_name

Actionability and button pointers:

• can_claim, can_approve
• claim_button_eid, approve_button_eid, disapprove_button_eid

Per-chore performance metrics:

• Counts: chore_points_earned, chore_claims_count, chore_completed_count, chore_approvals_count, chore_disapproved_count, chore_overdue_count, chore_missed_count
• Streaks: chore_current_streak, chore_longest_streak, chore_current_missed_streak, chore_longest_missed_streak, chore_last_longest_streak_date
• Last-event timestamps: last_claimed, last_approved, last_completed, last_disapproved, last_overdue, chore_last_missed
• Attribution: claimed_by, completed_by

Conditional attributes:

• custom_frequency_interval, custom_frequency_unit (when recurring frequency is custom)
• chore_approvals_today (for multi-approval reset modes and upon-completion reset)

Use can_claim and can_approve from the status sensor to decide action availability.

Read button IDs from status sensor attributes instead of constructing button entity IDs.

{% set s = 'sensor.henry_kidschores_chore_status_brush_teeth_am' %}
{% set can_claim = state_attr(s, 'can_claim') %}
{% set claim_button = state_attr(s, 'claim_button_eid') %}
{{ can_claim and claim_button is not none }}

For reusable blueprints or packages, resolve entity IDs from the registry/UI selection, not string concatenation.

• In Developer Tools → States, confirm the expected translation-keyed sensor exists (kid_chores_sensor / kid_chore_status_sensor).
• Verify purpose to ensure you are reading the intended sensor contract.
• If action buttons do not work, inspect claim_button_eid / approve_button_eid / disapprove_button_eid first.
• If timing appears wrong, inspect due_date, due_window_start, available_at, time_until_due, and time_until_overdue on the status sensor.

• Sensor implementations: custom_components/kidschores/sensor.py
• Attribute and key constants: custom_components/kidschores/const.py
• User-visible names/states: custom_components/kidschores/translations/en.json