locks: record capacity and clear semantics

reference/locks.md

@@ -1,9 +1,10 @@
 # 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:
+Two Kwikset HC620 Z-Wave (zwave_js) keypad locks:
+`lock.lodge_front_door_lock` (node 3) and `lock.bunkhouse_frontdoor_lock`
+(node 8). Each supports user-code slots 1–250; the automation and "Lock
+Management" Lovelace view manage shared logical slots 1–8 via helpers:
 `input_text.lock_slotN_user`, `input_text.lock_slotN_code`,
 `input_boolean.lock_slotN_lodge_enabled`, and
 `input_boolean.lock_slotN_bunkhouse_enabled` (N = 1–8).
@@ -13,12 +14,11 @@ hidden from the dashboard.
 </overview>
 
 <sync>
-All code writes go through `script.lock_sync_slot` (fields: `slot` 1–8), the
-single source of truth. Per slot and door it resolves the code (slot's own code
-if that door's toggle is on, else the slot-1 family code), refuses an invalid
-effective code for only that door with a door-specific notification, then does
-a UserCode CC `get` followed by `zwave_js.set_lock_usercode`. Every Z-Wave call
-uses `continue_on_error`, so one door never blocks the other.
+All code changes go through `script.lock_sync_slot` (fields: `slot` 1–8), the
+single source of truth. Per slot and door it refreshes the User Code CC cache,
+then writes the validated slot code when enabled or calls
+`zwave_js.clear_lock_usercode` when disabled. Every Z-Wave call uses
+`continue_on_error`, so one door never blocks the other.
 
 - `script.lock_sync_all_codes` — warns (persistent + `notify.mobile_app_donavan_s_iphone_16_pro`)
   if a lock's `*_node_status` sensor isn't alive/asleep, then runs
@@ -29,9 +29,9 @@ uses `continue_on_error`, so one door never blocks the other.
 - `automation.lock_codes_full_sync_self_heal` — full sync daily 04:00 and
   10 min after HA start, so transient failures heal within a day.
 
-Each disabled door slot is overwritten with the family code, so the family code
-exists in multiple slots. Slot 1's toggles are no-ops because its fallback is
-its own family code.
+An HC620 clear is confirmed by a refreshed `in_use: false` readback. Do not
+overwrite disabled slots with the family PIN: the lock rejects a duplicate PIN
+without changing the slot even when the service call returns successfully.
 </sync>
 
 <troubleshooting>