Home-AssistantConfig/config/script/README.md

Bear Stone Smart Home Documentation

Be sure to ⭐ my configuration repo so you can keep up to date on any daily progress!

Reusable scripts that other automations call for notifications, lighting, safety responses, and Joanna/BearClaw AGENT engineer handoffs. Pass variables in; let the script do the heavy lifting.

Quick navigation

• You are here: config/script/ (scripts library)
• Repo overview | Config index | Automations | Scenes |

Featured files to browse

File	Why it matters
	Single entrypoint for rich push notifications, with one or two optional action buttons, tags for clearing, and shared colored notification icons for household alerts.
	Single reconciler for grid, entry-point, occupancy, and target-temperature HVAC policy.
	Shared helper for tagged live activity/live update pushes and clear commands.
	Coordinates the bounded Driveway camera takeover and wake behavior across both household kiosks.
	Generic logbook.log helper for Activity feed entries (Issue #1550).
	Shared AGENT engineer dispatch contract that routes HA-detected issues into Joanna/BearClaw remediation.
	TTS/announcement orchestration with templated speech; speech processing can bypass LLM rewriting for exact messages and also routes garage/office Echo announcements.
	Conservative rain corroboration through the existing OpenAI AI Task and current exterior camera images. Returns a decision without controlling devices; requires usable recent Frigate camera reports, high-confidence visible rain or broadly wet exposed concrete, and inactive irrigation. Errors and uncertainty deny optional rain lighting.
	Seasonal lighting dispatcher that follows sensor.holiday_lighting_scene.
	Existing bedtime/away shutdown for interior lights, switches, media power, and the Paige lighting routine.
	Shared Home/Mobile lights-only shutdown with an explicit lamp-switch allowlist; uses the same scope as On Now.

Household notification icons

Driveway alerts, front-door package alerts/status checks, and check-garage-door reminders use separate stable tag values so each new notification replaces the previous one of its kind on each recipient's phone. Existing untagged notifications require one-time manual dismissal. The iOS destructive action option only colors an action button red; notification replacement uses tags.

Shared phone notifications sent through notify.ios_parents or notify.ios_family also join the household kiosk rotation for ten minutes. The kiosk feed observes these group calls, including callers outside notify_engine, and preserves phone recipients, actions, attachments, and urgency. Each slide shows the notification title, message, and sent time. A repeated tag replaces its earlier slide; clear_notification removes the matching tag. Individual phone notifications and device commands stay out of the shared rotation.

Both script.notify_engine and script.notify_engine_two_button accept notification_icon (an mdi: name), icon_url (a public or /local/ image), notification_icon_color (glyph hex color), and color (background hex color). On supported iOS apps, these appear as rounded sender icons and require a nonempty notification title. icon_url takes precedence over the MDI icon; colors apply only to MDI icons. See the Companion App documentation and issue #1773.

The shared helper gives existing notification groups a consistent palette without changing their grouping, recipients, action buttons, tags, or interruption levels:

Notification group	Icon	Background
Medicine	mdi:pill	Purple
Garbage_Reminders	mdi:trash-can-outline	Green
Welcome_Home	mdi:home-heart	Teal
360_alerts	mdi:map-marker-radius (arrival/departure callers override it)	Blue
Battery_Alert	mdi:battery-alert-variant-outline	Orange
maintenance	mdi:tools	Slate
Phyn	mdi:water-alert	Red
Tesla_Model_Y	mdi:car-electric	Blue
Tesla_Tire_Pressure	mdi:car-tire-alert	Orange
Tesla_Charge_Rate_Alarm	mdi:ev-station	Red
JuiceBox_Proxy_Offline	mdi:ev-station	Orange
water_heater	mdi:water-boiler-alert	Orange
RemoteLR	mdi:remote	Purple
Printer	mdi:printer	Slate
vacation	mdi:palm-tree	Teal
royal_caribbean_price_drop	mdi:ferry	Blue

Group lookup ignores case. An explicit icon overrides the preset; notification_icon: '' disables it. Other groups keep their existing payload unless a caller supplies an icon. Driveway, fridge-door, front-door package, and vacuum-help alerts supply their own icons while retaining their existing camera attachments where applicable. Untitled notifications and clear_notification commands receive no icon fields. Older apps or push paths that do not support custom icons retain the normal app icon.

Arrival alerts use a teal home-entry icon at home or a checked map pin at other monitored places; driving departures use a blue home-exit icon. The existing presence rules and notification groups stay in place. Grid status uses a red disconnected tower for outages and a green tower for restoration, with separate battery/HVAC icons for load shedding and recovery.

Lightning and high-wind warnings, open doors/garages, alarm-panel access, fridge temperature, server temperature, storage space, kitchen power, water-heater maintenance, house-sitter visits, and secure-house checks also pass explicit icons. Previously untitled door, alarm-panel, and storage alerts now have short titles so iOS can display their icons. The direct Roku remote-finder notification keeps its existing action payload and adds the same purple remote icon as its confirmation.

Joanna + BearClaw AGENT engineer handoff

script.joanna_dispatch is the shared handoff contract from Home Assistant automations into Joanna/BearClaw when Home Assistant detects something worth investigating or fixing.

Why we use it:

• Keeps one message schema for remediation context (trigger_context, source, summary, entity_ids, diagnostics, request, plus optional routing hints).
• Avoids repeating direct rest_command.bearclaw_command payload formatting in multiple packages.
• Lets Home Assistant stay focused on detection, timing, and routing while Joanna acts as the AGENT engineer for infrastructure triage and recommended remediation.
• Makes resolution-trigger automations easier to review, update, and audit.

What the helper normalizes before the BearClaw intake call:

• trigger_context, source, and summary so every dispatch has traceable origin details.
• entity_ids from either a YAML list or a comma-delimited string.
• diagnostics from either free text or structured mappings/sequences.
• request guardrails so Joanna defaults to investigation/recommendation, not blind resets or power-cycles.
• domain_hint/lane_hint default to BearClaw ops routing so HA infrastructure text does not drift into another domain parser.

Current automations that kick off automated resolutions (via script.joanna_dispatch):

Automation ID	Alias	File
mqtt_open_repair_on_failure	MQTT - Open Repair On Failure
onenote_indexer_failure_open_repair	OneNote Indexer - Open Repair On Failure
infra_backup_nightly_verification	Infrastructure - Backup Nightly Verification
infra_monthly_log_hygiene_review	Infrastructure - Monthly HA Log Hygiene Review
infra_nebula_sync_health_dispatch	Infrastructure - Nebula Sync Health Dispatch
infra_pihole_iot_dns_drift_dispatch	Infrastructure - Pi-hole IoT DNS Drift Dispatch
infra_website_down_repair_and_dispatch	Infrastructure - Website Down Repair And Dispatch
docker_state_sync_repairs_dynamic	Docker State Sync - Repairs (Dynamic)
docker_group_reconcile_weekly_joanna_review	Docker Group Reconcile - Weekly Joanna Review
docker_host_disk_pressure_monitor	Docker Host Disk Pressure Monitor
proxmox_updates_joanna_dispatch	Proxmox Updates Joanna Dispatch
tugtainer_dispatch_joanna_for_available_updates	Tugtainer - Dispatch Joanna For Available Updates
tugtainer_dispatch_joanna_for_home_assistant_core_digest	Tugtainer - Dispatch Joanna For Home Assistant Core Digest
unifi_ap_no_clients_repair_combined	Unifi AP Create Repair Issue after 5m of 0 Clients
proxmox_runtime_repairs	Proxmox Runtime Repair Issues
proxmox_disk_pressure_repairs	Proxmox Disk Pressure Repair Issues
synology_dsm_open_repair_and_dispatch	Synology DSM - Open Repair And Dispatch
processmonitor_disk_use_joanna_review	Self Heal Disk Use Joanna Review
rheem_water_heater_alert_incident	Rheem Water Heater Alert Incident
rheem_water_heater_incident_reconcile	Rheem Water Heater Incident Reconcile
1ce3cb43-0e27-4c53-acdd-d672396f3559	Disk Use Alarm

Tips

• Keep scripts generic, route data via data:/variables:, and reuse everywhere.
• If you copy a script, rename any alias and id fields to avoid duplicates.

All of my configuration files are tested against the most stable version of home-assistant.

Still have questions on my Config?
Message me on X :

You can buy me a coffee

Affiliate Disclosure