various tidyups

packages/alexa_tplink_actions.yaml

@@ -1,5 +1,52 @@
+#:########################################################################################:#
+# Alexa TP-Link Guest Wi-Fi Package                                                      #
+#:########################################################################################:#
+#
+# TITLE:
+#   Alexa TP-Link Guest Wi-Fi
+#
+# FILE:
+#   packages/alexa_tplink_actions.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured documentation and automation descriptions.
+#
+#   V1.0
+#     - Initial Alexa-mediated TP-Link guest-network controls.
+#
+# PURPOSE:
+#   Enables or disables the TP-Link guest Wi-Fi network by sending custom Alexa
+#   requests through the kitchen Echo Show.
+#
+# DEPENDENCIES:
+#   - input_boolean.wifi_guest_network is a UI-managed helper that represents
+#     the requested guest-network state.
+#   - media_player.view_rd_kitchen_echo_show must be available through the Alexa
+#     Media Player integration.
+#   - The Alexa account must have a working, linked TP-Link skill.
+#
+# ALEXA REQUESTS:
+#   - On:  ask t.p.link to enable guest network
+#   - Off: ask t.p.link to disable guest network
+#
+# OPERATION NOTES:
+#   - The helper records requested state; it does not confirm router state.
+#   - If Alexa or the TP-Link skill fails, the helper can disagree with the
+#     actual guest-network state.
+#   - After the helper remains on for two hours, it is turned off. That state
+#     change then sends the Alexa disable request.
+#   - The two-hour state-trigger period does not persist through a Home Assistant
+#     restart or automation reload.
+#
+#:########################################################################################:#
+
 automation:
   - alias: "Turn on the Wifi Guest Network"
+    description: "Asks the linked TP-Link Alexa skill to enable the guest Wi-Fi network."
     mode: single
     triggers:
       - trigger: state
@@ -14,6 +61,7 @@ automation:
           media_content_id: ask t.p.link to enable guest network
 
   - alias: "Turn off the Wifi Guest Network"
+    description: "Asks the linked TP-Link Alexa skill to disable the guest Wi-Fi network."
     mode: single
     triggers:
       - trigger: state
@@ -28,6 +76,7 @@ automation:
           media_content_id: ask t.p.link to disable guest network
 
   - alias: "Switch guest network off after time"
+    description: "Turns off the guest-network helper after it remains on for two hours."
     mode: single
     triggers:
       - trigger: state