adjust docs

README.md

@@ -131,7 +131,8 @@ Example schema:
       "name": "TV Lights Scene",
       "type": "tap",
       "tap_action": {
-        "service": "scene.turn_on"
+        "service": "scene.turn_on",
+        "pin": true
       }
     }
   ]
@@ -264,6 +265,8 @@ The application timeout prevents the HomeAssistant App running on your watch whe
 
 There is a second timeout value for confirmation views. This is intended for use with more sensitive toggles so that the confirmation view is not left open and forgotten and then confirmed accidentally without you noticing. **We cannot advise you this is safe, be careful what you toggle with the watch application!**
 
+The confirmation timeout is also used for the maximum time between clicks in the PIN confirmation dialog. The PIN confirmation provides a more secure alternative for toggling security-sensitive actions.
+
 There is a toggle setting for "text alignment" that provides finer adjustment for right-to-left languages. Perhaps this could be made automatic based on device language?
 
 The application and widget both include a background service to report your watch's battery level and charging status. You may enable a background service to report the battery level to your Home Assistant. This is not available over your Bluetooth connection like with other Bluetooth devices as Garmin did not implement it. This no longer requires any setup, and we offer this [trouble shooting](TroubleShooting.md#watch-battery-level-reporting) guide. The last field here is readonly and allows the user to copy & paste the Webhook ID setup by the application when required for this trouble shooting guide.

examples/Actions.md

@@ -38,6 +38,22 @@ For example:
 }
 ```
 
+**Please be advised that for security sensitive actions, a PIN confirmation should be used.**
+
+This can be enabled by setting the `pin` field in the `tap_action`. The `pin` field overrides `confirm`. Explicitly setting `confirm` is not necessary.
+
+The 4-digit PIN is set globally for all actions in the app settings in Connect IQ.
+
+```json
+  "tap_action": {
+    "pin": true
+  }
+```
+
+When entering an invalid PIN for the fifth time within 2 minutes, the PIN dialog will be locked for all actions for the next 10 minutes. Entering a valid PIN will always reset the failure counter.
+
+<img src="../images/pin_view.png" width="200" title="Confirmation View"/>
+
 Note that for notify events, you _must_ not supply an `entity_id` or the API call will fail. There are other examples too.
 
 ```json

examples/Switches.md

@@ -22,7 +22,20 @@ And with an optional confirmation:
    "tap_action": {
      "confirm": true
    }
- },
+ }
+```
+
+or an optional PIN confirmation:
+
+```json
+ {
+   "entity": "light.exterior",
+   "name": "Exterior Lights",
+   "type": "toggle",
+   "tap_action": {
+     "pin": true
+   }
+ }
 ```
 
 To support a non-standard light, switch, or automation as a toggle menu item you may like to define a custom switch. In order to facilitate custom switches at this time, you must create a template switch in HomeAssistant.

examples/Templates.md

@@ -101,10 +101,10 @@ Here we also use the else clause as well to give proper text instead of just `on
 > [!IMPORTANT]
 > We advise users against adding security devices.
 
-However, users are doing this **against our advice** and asking how to operate 'covers'. This is an example of toggling a garage door open and closed with confirmation. *Do this at your own risk*.
+However, for users doing this **against our advice**, we strongly recommend to secure confirmation of the action using our PIN confirmation dialog.
+This an example of toggling a garage door open and closed with a PIN confirmation. *Do this at your own risk*.
 
-In order to provide some additional security, users with touch devices can now choose to use a PIN confirmation when using actions annotated with `"confirm": true`.
-This is activated once a PIN is configured in the application settings. The PIN needs to be a 4-digit number.
+The PIN confirmation is activated for actions with `"pin": true`. The PIN is configured globally in the application settings. The PIN needs to be a 4-digit number.
 The user has 5 attempts to provide a valid PIN within 2 minutes. If too many failures have been detected during this time, the PIN dialog will be locked for 10 minutes.
 
 Note: Only when you use the `tap_action` field do you also need to include the `entity` field. This is a change to a previous version of the application, hence the presence of the `entity` field will be ignored for backwards compatibility, and the schema will provide a warning only.
@@ -117,7 +117,7 @@ Note: Only when you use the `tap_action` field do you also need to include the `
   "content": "{% if is_state('binary_sensor.garage_connected', 'on') %}{{state_translated('cover.garage_door')}} - {{state_attr('cover.garage_door', 'current_position')}}%{%else%}Unconnected{% endif %}",
   "tap_action": {
     "service": "cover.toggle",
-    "confirm": true
+    "pin": true
   }
 }
 ```