From 5e213759d6aed9bb6fea8b1bcb6fd9951c6b1db9 Mon Sep 17 00:00:00 2001
From: Claude <anthropic@fritz.family>
Date: Sun, 5 Jul 2026 19:22:46 +0000
Subject: [PATCH] Add locks reference: code slot helpers, sync script,
 usercode-cache troubleshooting

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 SKILL.md           |  7 +++++++
 reference/locks.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 reference/locks.md

diff --git a/SKILL.md b/SKILL.md
index 8f878b3..d566369 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -44,6 +44,13 @@ user-invocable: true
     keywords=["home assistant", "HA", "home.thelonglakelodge.com", "matter", "nest", "thermostat", "climate", "dashboard", "lovelace", "HVAC", "in floor heating", "environmentals", "core_matter_server", "172.24.24.50"] />
 </references>
 
+<references>
+  <reference file="reference/locks.md"
+    summary="Door locks: two zwave_js keypad locks, 8 code slots via input_text/input_boolean helpers, script.lock_sync_all_codes + per-slot automations, fix for 'userCode for code slot N not found'"
+    categories=["home-automation"]
+    keywords=["lock", "locks", "door code", "door codes", "usercode", "code slot", "keypad", "lock_sync_all_codes", "set_lock_usercode", "zwave", "front door", "bunkhouse"] />
+</references>
+
 <references>
   <reference file="reference/website.md"
     summary="Lodge website: Latchkey managed-website service (latchkey-sites bucket, sites anycast edge, auto-TLS), Manage-files editing, /welcome PDF stub"
diff --git a/reference/locks.md b/reference/locks.md
new file mode 100644
index 0000000..7ff3020
--- /dev/null
+++ b/reference/locks.md
@@ -0,0 +1,32 @@
+# Door Locks & Codes
+
+<overview>
+Two Z-Wave (zwave_js) keypad locks: `lock.lodge_front_door_lock` (node 3) and
+`lock.bunkhouse_frontdoor_lock`. 8 shared code slots, managed from the
+"Lock Management" Lovelace view via helpers:
+`input_text.lock_slotN_user`, `input_text.lock_slotN_code`,
+`input_boolean.lock_slotN_enabled` (N = 1–8).
+Slot 1 = Fritz family, 2 = cleaner, 4 = carpenter, 5 = backup.
+</overview>
+
+<sync>
+`script.lock_sync_all_codes` (mode: queued) walks slots 1–8; for each slot it
+calls `zwave_js.set_lock_usercode` on BOTH locks — the slot's code if its
+`_enabled` boolean is on, otherwise the slot-1 family code (hardcoded in the
+script's default branches). `automation.lock_slot_N_sync_both_locks` (per slot)
+also pushes on helper change. An error on any step ABORTS the script — later
+slots and the second lock do not sync.
+
+The `input_boolean.lock_code_slot_N_*` / `input_text.lock_code_slot_N_*` /
+`input_boolean.lock_slotN_lodge/bunkhouse_enabled` entities are unavailable
+leftovers from earlier schemes — ignore.
+</sync>
+
+<troubleshooting>
+Error `userCode for code slot N not found` from `zwave_js.set_lock_usercode`
+= Z-Wave JS value cache has no userCode value for that slot (never
+queried/interviewed), NOT a lock or code problem. Fix by forcing a UserCode CC
+read to repopulate the cache, then re-run the sync script:
+`zwave_js.invoke_cc_api {device_id, command_class: "99", method_name: "get", parameters: [N]}`.
+(2026-07-05: lodge slot 3 hit this; gets were run for slots 1–8 on both locks.)
+</troubleshooting>