From 141f8220d71630c6f32adb2888b7a8d08e79aebb Mon Sep 17 00:00:00 2001
From: Till Wegmueller <toasterson@gmail.com>
Date: Sat, 28 Mar 2026 23:28:55 +0100
Subject: [PATCH] Update ADR-013: NFC charging pad as smart card reader

Add wireless charging pad mode -- phone on Qi pad acts as smart card
in a reader slot. NFC provides crisp insert/remove semantics without
RSSI ambiguity. Combined NFC+BLE mode for heartbeat during brief
NFC interrupts. Configurable per-deployment: centimeter range (pad)
vs meter range (pocket) vs combined.
---
 docs/ai/adr/013-smartphone-proximity-token.md | 33 +++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/docs/ai/adr/013-smartphone-proximity-token.md b/docs/ai/adr/013-smartphone-proximity-token.md
index 8d22c04..327c60d 100644
--- a/docs/ai/adr/013-smartphone-proximity-token.md
+++ b/docs/ai/adr/013-smartphone-proximity-token.md
@@ -52,13 +52,42 @@ WayRay Client (BLE scanner):
   5. If multiple tokens: nearest (highest RSSI) wins
 ```
 
-### NFC -- Complementary
+### NFC -- Complementary (and Charging Pad Mode)
 
 Phone tap on NFC reader for explicit authentication:
 - Quick deliberate action (tap to connect)
 - Works as fallback when BLE is disabled
 - Can trigger initial token provisioning
-- Very short range (~4cm) -- no proximity tracking
+- Very short range (~4cm) -- no proximity tracking, clean binary signal
+
+**Wireless charging pad as card reader:** In high-security or dense office deployments, the client's NFC reader can be embedded in (or placed next to) a Qi wireless charging pad. The phone on the pad is simultaneously charging and authenticating -- exactly mimicking a smart card in a reader slot. NFC provides the crisp insert/remove semantics (present = attached, lifted = detached) without RSSI ambiguity. The companion app responds to NFC with the session token via HCE (Host Card Emulation on Android) or Core NFC (iOS).
+
+**Combined NFC + BLE mode:** For deployments that want both:
+- NFC: immediate attach when phone placed on pad (desk-distance, deliberate)
+- BLE: sustained heartbeat confirming phone is still present (survives brief NFC interrupts)
+- NFC absence + BLE absence: detach (phone physically removed from area)
+
+This gives precise control -- some offices want centimeter-range "phone on pad" behavior, others want meter-range "phone in pocket" behavior. Same `TokenProvider` trait, deployment configuration picks the mode:
+
+```toml
+# /etc/wayray/token.toml
+
+[proximity]
+# "ble" = walk-up proximity (meter range)
+# "nfc" = charging pad / tap (centimeter range)
+# "ble+nfc" = NFC for attach, BLE for heartbeat
+# "ble|nfc" = either can attach independently
+mode = "nfc"
+
+[ble]
+rssi_threshold = -70    # dBm
+attach_delay = 2        # seconds
+detach_delay = 10       # seconds
+
+[nfc]
+# No thresholds needed -- NFC is binary (present/absent)
+detach_delay = 3        # seconds grace period for brief lifts
+```
 
 ### UWB (Ultra-Wideband) -- Future