From f51ba718aaa82568d496c6e67d0db222f269ca6a Mon Sep 17 00:00:00 2001
From: Mortdecai <admin@mortdec.ai>
Date: Sun, 7 Jun 2026 13:42:40 -0400
Subject: [PATCH] docs: HA script + Google Home exposure steps

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/ha-setup.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/ha-setup.md

diff --git a/docs/ha-setup.md b/docs/ha-setup.md
new file mode 100644
index 0000000..1974685
--- /dev/null
+++ b/docs/ha-setup.md
@@ -0,0 +1,73 @@
+# HA + Google Home setup — POS Briefing button
+
+The MQTT bridge (`pos-briefing-mqtt.service` on steel141) auto-creates an HA
+button via MQTT discovery. Google's `google_assistant` integration does not
+support `button` entities, so we wrap the button in a `script` (scripts expose to
+Google as a **Scene** = a tappable button in the Home app).
+
+Chain: **Google Home tap → HA script → `button.press` → MQTT `posbriefing/button/press`
+→ bridge runs `pos_briefing.py` → prints on the TM-m30.**
+
+## 0. Confirm the entity exists
+Settings → Devices & Services → **MQTT** → device **POS Briefing**. You should see
+button **Print Daily Briefing** (entity `button.print_daily_briefing`). Pressing it
+in HA should print a receipt. (Status is published on `posbriefing/status`:
+`idle`/`printing`/`ok`/`error:<msg>`; availability on `posbriefing/availability`.)
+
+If the entity id differs, use whatever HA shows in the script below.
+
+## 1. Add the script
+Settings → Automations & Scenes → **Scripts** → (top-right) Edit in YAML, or paste
+into `scripts.yaml`:
+```yaml
+print_daily_briefing:
+  alias: Print Daily Briefing
+  sequence:
+    - service: button.press
+      target:
+        entity_id: button.print_daily_briefing
+  mode: single
+```
+
+## 2. Expose the script to Google
+Add to the SAME `google_assistant:` block that already exposes the LG TV switch
+(keep your existing `project_id` / `service_account` lines):
+```yaml
+google_assistant:
+  project_id: <your existing project_id>
+  service_account: !include <your existing service_account file>
+  report_state: true
+  exposed_domains:
+    - switch
+  entity_config:
+    script.print_daily_briefing:
+      name: Print Daily Briefing
+      expose: true
+```
+Reload (Developer Tools → YAML → "Google Assistant" or restart HA).
+
+Reminders from the lgtv 2026-06-06 linking (already satisfied for your setup):
+manual `google_assistant` integration (not Nabu Casa); account-linking scopes must
+include `email` + `name`; the **"HTTP basic auth header" checkbox must be OFF**; the
+Google **Test** must be activated by the same account used in the Home app
+(slingshooter08). The GCP OAuth consent screen is unrelated to smart-home linking —
+don't touch it.
+
+## 3. Sync to Google Home
+Say "Hey Google, sync my devices" (or re-run device setup in the Home app). The
+button appears as **Print Daily Briefing**; tapping it prints the receipt.
+
+## Optional: surface print status in HA
+Add an MQTT sensor (configuration.yaml) if you want to see the last result:
+```yaml
+mqtt:
+  sensor:
+    - name: "POS Briefing Status"
+      state_topic: "posbriefing/status"
+      availability_topic: "posbriefing/availability"
+```
+
+## Notes
+- A print takes ~1–2 min (gemma4:26b summarization). The button returns immediately;
+  watch `posbriefing/status` go `printing` → `ok`.
+- A second press while one is in flight is ignored (debounced) — no double prints.