@homebridge-plugins/homebridge-eufy-security 4.6.0-beta.4 → 4.6.0-beta.41

package/.claude/CLAUDE.md

@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the homebridge-eufy-security plugin.
+
+## Project Overview
+
+Homebridge plugin that exposes Eufy Security devices to Apple HomeKit. Published as `@homebridge-plugins/homebridge-eufy-security` under the `homebridge-plugins` GitHub organization.
+
+Depends on `eufy-security-client` (upstream: bropat/eufy-security-client) for cloud API, P2P, push notifications, and MQTT communication.
+
+For detailed functional requirements, device coverage, configuration options, and architecture boundaries, see `.claude/PRD.md`.
+
+## Build & Dev Commands
+
+```bash
+npm run build          # rimraf dist -> tsc -> copy media/ to dist/
+npm run build-plugin   # rimraf dist -> tsc (no media copy)
+npm run lint           # eslint 'src/**/*.ts' --max-warnings=0
+npm run lint-fix       # eslint with --fix
+```
+
+- No test suite -- there are no unit or integration tests
+- Output: `dist/`
+- `--max-warnings=0` is enforced -- all warnings must be fixed before committing
+- ESLint uses flat config (`eslint.config.mjs`); `@typescript-eslint/no-explicit-any` is globally disabled -- do not add eslint-disable comments for it
+- Run `npm run lint` and `npm run build` before pushing
+
+## Architecture
+
+Entry point `src/index.ts` registers `EufySecurityPlatform` with Homebridge. The platform class (`src/platform.ts`) is the core -- it initializes the `EufySecurity` client, discovers devices, and creates HomeKit accessories.
+
+**Accessory classes** in `src/accessories/` map Eufy device types to HomeKit services:
+- `BaseAccessory.ts` -- root base class (characteristic registration, service pruning)
+- `Device.ts` (`DeviceAccessory`) -- extends `BaseAccessory`; adds sensor/battery services, property helpers
+- `CameraAccessory` -- cameras, doorbells, floodlights (handles streaming delegates); extends `DeviceAccessory`
+- `StationAccessory` -- base stations (security system service for arm/disarm); extends `BaseAccessory` directly
+- `LockAccessory`, `EntrySensorAccessory`, `MotionSensorAccessory`, `SmartDropAccessory` -- extend `DeviceAccessory`
+- `AutoSyncStationAccessory` -- virtual accessory that syncs station guard mode with HomeKit
+
+**Streaming pipeline** in `src/controller/`:
+- `streamingDelegate.ts` -- HomeKit camera streaming (FFmpeg-based)
+- `recordingDelegate.ts` -- HomeKit Secure Video recording
+- `snapshotDelegate.ts` -- snapshot handling
+- `LocalLivestreamManager.ts` -- manages P2P livestream sessions
+
+**Utilities** in `src/utils/`: logging (`utils.ts`), FFmpeg wrapper (`ffmpeg.ts`), two-way audio (`Talkback.ts`), config schema (`configTypes.ts`), internal interfaces (`interfaces.ts`).
+
+**Constants** in `src/settings.ts`: HKSV segment lengths, snapshot cache ages, streaming bitrate headroom, IDR intervals -- reference this when tuning streaming or recording behaviour.
+
+**Plugin UI** in `homebridge-ui/`: `server.js` (plain JS, eslint-ignored) handles UI server logic and diagnostics generation. The UI and the plugin runtime (`src/`) are **separate processes** that share state through `accessories.json` on disk (written by `src/utils/accessoriesStore.ts`, read by `homebridge-ui/server.js`). Both independently import `eufy-security-client` types (`DeviceType`, `PropertyName`, `Device`, etc.) -- changes to the device/station record shape must be kept in sync between `accessoriesStore.ts` and `server.js`.
+
+### Key source files for device registration and triage
+
+- `src/platform.ts` (`register_device`) -- device registration logic; devices can stack multiple capabilities (independent `if` blocks, not `else if`)
+
+## Key Technical Details
+
+- ESM project (`"type": "module"`, `"module": "NodeNext"`) -- imports must use `.js` extensions (NodeNext resolution requires explicit extensions)
+- TypeScript strict mode, ES2022 target (`noImplicitAny: false` relaxes implicit-any checks)
+- Node.js 20, 22, or 24 required
+- Homebridge >=1.9.0 or ^2.0.0-beta
+- Uses `ffmpeg-for-homebridge` for video transcoding
+- `src/version.ts` is auto-generated at prebuild time -- do not edit manually
+- `prepublishOnly` runs lint + build automatically before `npm publish`
+- For local development, `eufy-security-client` can be pointed to a local path (e.g. `"../eufy-security-client"`)
+
+## Git Workflow
+
+**IMPORTANT: Create the branch BEFORE editing any files.**
+
+```bash
+# Create dedicated branch from beta before making any changes
+git checkout beta-*.*.* && git pull origin beta-*.*.*
+git checkout -b [fix/feat/chore]/<short-description>
+
+# Stage and commit each change individually
+git add <file>
+git commit -m "fix: <concise description of what changed and why>"
+
+# Push and create PR
+git push -u origin fix/<short-description>
+gh pr create --base beta-*.*.* --title "<concise title>" --body-file /tmp/pr-body.md
+```
+
+- Branch from `beta-*.*.*`, not `master`
+- PR target: `beta-*.*.*`
+- Branch naming: `fix/`, `feat/`, `chore/` prefix
+
+### Commit message rules
+
+- Single line, no line breaks mid-sentence
+- Describe the **spirit** of the change, not the code diff
+- No Co-Authored-By
+
+### PR body
+
+- Write to `/tmp/pr-body-<branch>.md` using file creation -- **never** use heredoc (`cat << EOF`) in the terminal (quotes and special characters break it)
+- Describe the **spirit** of the change, not the code diff
+- Concise description of the problem and fix
+- PR body is **not** the release note -- keep it focused on the code change for reviewers
+- No Co-Authored-By
+
+### Release notes
+
+- Write to `/tmp/release-notes-<version>.md` using file creation
+- **Audience is end users** -- focus on what matters to them: new devices, behaviour changes, removed settings, required actions
+- **Concise, bullet-driven** -- no markdown tables, no verbose paragraphs. Short section intros (1-2 sentences max) followed by bullet lists
+- **No internal milestones** -- don't mention "first GA since X" or beta iteration counts
+- **Structure for a branch** (e.g., `4.4.x`), not a single version:
+  - Individual `## v4.4.x` entries at the top with version-specific changes
+  - A shared `## What's in 4.4.x` section below covering the full branch
+- **Required actions front and center** -- if users need to change config or upgrade Node.js, say so early and clearly
+- **Tone**: direct, no filler, no emojis
+
+### Issue comments
+
+- Use `gh issue comment <number> --repo homebridge-plugins/homebridge-eufy-security --body "<message>"`
+- Use first person ("I")
+- Thank the user by @mention
+- Be formal and concise
+- **Audience is end users** -- keep language simple, no internal jargon
+- Don't scope a fix to a specific device when it applies broadly
+- When a fix is merged, check the published beta version (`npm view @homebridge-plugins/homebridge-eufy-security dist-tags`) and mention it in the comment
+
+## Dependency Policy -- `eufy-security-client`
+
+**CRITICAL:**
+- **`beta-*.*.*` branches** -- use the `dev` dist-tag (`"eufy-security-client": "dev"`)
+- **`master` branch** -- **NEVER** use the `dev` dist-tag. Always use a pinned stable version (e.g. `"^3.7.2"`). Before merging to master, replace `"dev"` with the corresponding stable release version.
+
+When updating the `eufy-security-client` version in `package.json`:
+1. Check the upstream changelog and README at https://github.com/bropat/eufy-security-client/blob/master/README.md
+2. Identify breaking changes, new features, or device support changes
+3. Summarize the impact in the PR body
+4. If there are breaking changes, note any required code adjustments
+
+## Skills
+
+Skills in `.claude/skills/` provide structured workflows for common tasks:
+
+| Skill | Purpose |
+|---|---|
+| `planner` | Build a step-by-step action plan with guardrails before coding |
+| `developer` | Execute code changes following an approved plan or direct instructions |
+| `qa` | Verify build, lint, imports, architecture, and git hygiene before pushing |
+| `architect` | Quick codebase questions, mini-bug debugging, workflow improvement |
+| `support` | Triage GitHub issues using diagnostics archives and logs |
+| `new-device-support` | Full workflow to add a new Eufy device type across both repos |
+
+Typical flow: **planner** -> **developer** -> **qa**. Use **architect** for exploration and **support** for issue triage.
+
+## Diagnostic Triage
+
+For issue triage, use the `support` skill with an issue number (e.g. `/support 423`). For the full triage reference, see `.github/prompts/diag-triage.prompt.md`. For adding new device types, use the `new-device-support` skill. Key points:
+
+- Diagnostics archives are encrypted (RSA-4096 + AES-256-GCM); decrypt with `node scripts/decrypt-diagnostics.mjs <file>.tar.gz`
+- Always check archive completeness before analysis -- missing runtime logs means the plugin wasn't running
+- When diagnostics are incomplete or debug is disabled, ask the user to upgrade to the latest [beta](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Special-Version-(BETA---RC---HKSV)) and follow the [Basic Troubleshooting](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Basic-Troubleshooting) steps to enable Detailed Logging, reproduce the issue, and re-export diagnostics
+- Narrow down whether the issue is in `homebridge-eufy-security` (accessory registration, HomeKit mapping, config handling) or in `eufy-security-client` (device discovery, property events, P2P, push notifications)
+- If the environment indicates HOOBS: label `hoobs` + `wontfix` and close -- HOOBS is not supported
+
+### Label recommendations
+
+| Label | When to use |
+|---|---|
+| `depends on eufy-security-client` | Issue originates in bropat's eufy-security-client library |
+| `device-support` | New device type support request |
+| `debug log missing` | Diagnostics lack logs or debug mode was disabled |
+| `configuration issue` | Problem caused by user config |
+| `livestream` | Camera livestream, video feed, P2P, RTSP, streaming failures |
+| `question` | Further information is requested |
+| `resolved in beta` | Fix already in current beta |
+| `needs triage` | New issue awaiting initial analysis |
+| `duplicate` | Issue or PR already exists |
+| `hoobs` | HOOBS-specific -- label as `hoobs` + `wontfix` and close |

package/.claude/PRD.md

@@ -0,0 +1,241 @@
+# PRD -- homebridge-eufy-security
+
+Product Requirements Document for `@homebridge-plugins/homebridge-eufy-security`.
+
+## Purpose
+
+Expose Eufy Security devices to Apple HomeKit via Homebridge. Users control cameras, doorbells, locks, sensors, base stations, and delivery boxes from the Home app -- including live video, HomeKit Secure Video recording, arm/disarm, and two-way audio.
+
+## Target Users
+
+Homebridge users with Eufy Security hardware who want native HomeKit integration without Eufy's official HomeKit firmware (limited or unavailable for most devices).
+
+## System Requirements
+
+| Requirement | Value |
+|---|---|
+| Node.js | 20, 22, or 24 |
+| Homebridge | >=1.9.0 or ^2.0.0-beta |
+| Eufy Account | Dedicated guest account (admin accounts blocked) |
+| FFmpeg | Bundled via `ffmpeg-for-homebridge` |
+
+---
+
+## Functional Requirements
+
+### FR-1: Device Discovery & Registration
+
+- Connect to Eufy cloud via `eufy-security-client` (cloud API, P2P, push notifications, MQTT)
+- Discover stations and devices automatically on plugin startup
+- Batch device processing with 10-second debounce to avoid thrashing during sync
+- Hot-add/remove devices after initial discovery completes
+- Restore cached accessories across Homebridge restarts
+- Prune stale cached accessories when `cleanCache: true`
+- Devices can stack multiple capabilities (camera + motion sensor + doorbell) via independent registration blocks
+
+### FR-2: Camera Streaming
+
+#### FR-2.1: Live Streaming
+- P2P direct stream (default, low latency)
+- RTSP stream (opt-in per camera)
+- FFmpeg transcoding to H.264 + AAC-ELD with SRTP encryption
+- Hardware encoder detection: VideoToolbox (macOS), V4L2 (Raspberry Pi), VAAPI/QSV (Linux)
+- Fallback to libx264 software encoding
+- Configurable max resolution, bitrate, frame rate
+- Max concurrent streams per camera (default 2)
+- Configurable livestream duration (default 30s, max 86400s)
+- RTCP keep-alive monitoring with inactivity timeout
+
+#### FR-2.2: HomeKit Secure Video (HKSV)
+- Record motion/doorbell events as fMP4 fragments
+- 4-second segment length (HomeKit requirement)
+- 8-second timeshift buffer for pre-motion capture
+- Audio recording (AAC-ELD or AAC-LC per HomeKit config)
+- Snapshot capture during active recording
+- Max 3 segment errors before connection reset
+
+#### FR-2.3: Snapshots
+- Four handling modes: AlwaysFresh, Balanced, CloudOnly (default), Auto
+- Intelligent caching with configurable thresholds (fresh: 15s, balanced: 30s)
+- Placeholder images for offline/disabled/unavailable states
+- Cloud snapshot skip within 30s of livestream capture (prevents quality degradation)
+
+#### FR-2.4: Two-Way Audio (Talkback)
+- Bidirectional audio via duplex stream
+- Caches audio data until device is ready
+- 2-second silence auto-stop
+- Configurable channel count (mono default)
+
+### FR-3: Security System (Stations)
+
+- Map Eufy guard modes to HomeKit security states (Stay, Away, Night, Off)
+- Per-station guard mode mapping (configurable numeric mode values)
+- Manual alarm trigger with configurable duration and HomeKit mode filter
+- Alarm arm delay and alarm event handling via push notifications
+- Multi-station sync via virtual AutoSyncStationAccessory (opt-in)
+
+### FR-4: Locks
+
+- Lock/unlock control via HomeKit LockMechanism service
+- Lock jammed state detection via push notifications
+- Lock management service (auto-security timeout, admin-only access)
+
+### FR-5: Sensors
+
+#### FR-5.1: Motion Sensors
+- Standalone motion detection service
+- Camera-integrated motion with configurable timeout
+- Multi-event support: person, pet, vehicle, sound, crying, dog, stranger
+
+#### FR-5.2: Entry Sensors (Contact Sensors)
+- Door/window open/closed state
+
+### FR-6: Doorbells
+
+- ProgrammableSwitchEvent on ring
+- Optional motion-triggers-doorbell mode
+- Optional indoor chime control switch
+- Snapshot delay on doorbell ring (configurable)
+
+### FR-7: Floodlights
+
+- Lightbulb service for floodlight control
+- Combined camera + light capabilities
+
+### FR-8: Smart Drop (Package Boxes)
+
+- One-way open via LockMechanism
+- Package delivery detection via ContactSensor
+
+### FR-9: Per-Device Switches
+
+- Enable/disable device switch
+- Motion detection toggle switch
+- Light control switch (floodlights)
+- Indoor chime toggle switch
+- All switches individually configurable per camera
+
+---
+
+## Configuration Requirements
+
+### CR-1: Global Configuration
+- Eufy credentials (username, password, device name)
+- Country code (ISO 3166-1 alpha-2)
+- Polling interval (default 10 minutes)
+- Global guard mode mapping (hkHome, hkAway, hkNight, hkOff)
+- Device/station ignore lists by serial number
+- Debug logging toggle (`enableDetailedLogging`)
+- Log file opt-out (`omitLogFiles`)
+- Cache cleanup toggle (`cleanCache`, default true)
+- Auto-sync station mode toggle
+- Embedded PKCS1 support toggle (Node.js <24.5 workaround)
+
+### CR-2: Per-Camera Configuration
+- Stream source: P2P or RTSP
+- Enable/disable camera streaming entirely
+- Snapshot handling method (AlwaysFresh, Balanced, CloudOnly, Auto)
+- Audio enable/disable
+- Talkback enable/disable with channel count
+- HKSV recording duration
+- Motion timeout
+- Per-switch visibility (enable, motion, light, indoor chime)
+- Full FFmpeg video config override (codec, resolution, bitrate, filters, encoder options, custom binary path)
+
+### CR-3: Per-Station Configuration
+- Guard mode mapping overrides (hkHome, hkAway, hkNight, hkOff)
+- Manual alarm trigger modes and duration
+
+---
+
+## Plugin UI Requirements
+
+### UI-1: Device Discovery
+- Login flow with TFA and captcha support
+- Discovery progress reporting (authenticating, queuing, processing, done)
+- Skip button for unsupported device intel wait
+- Admin account detection and blocking
+
+### UI-2: Device Management
+- Display discovered stations and devices with type, capabilities, power status
+- Show unsupported devices separately
+- Detect running plugin via heartbeat (accessories.json `storedAt` < 90s old)
+- Load stored accessories from cache when plugin is not running
+
+### UI-3: Diagnostics
+- Generate encrypted diagnostics archive (RSA-4096 + AES-256-GCM)
+- Rate-limited to 60-second minimum between downloads
+- Archive includes: config (sanitized), all log files, accessories.json, system info
+- Decryptable via `node scripts/decrypt-diagnostics.mjs`
+
+### UI-4: Storage Management
+- Reset plugin storage (persistent.json, accessories.json)
+- Clean all storage option
+- System info endpoint (plugin version, Node.js version, host OS)
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Logging
+- Rotating file streams (daily rotation, max 3 archives, 200MB limit)
+- Styled console output (color-coded by level)
+- Debug mode adds file:line references and library-level logging
+- Separate log streams: plugin, library, UI server, UI library, FFmpeg (global + per-camera + snapshots)
+
+### NFR-2: Reliability
+- Connection retry (3 attempts, 30s backoff) on Eufy cloud failure
+- P2P stream retry with exponential backoff (2-10s, max 3 attempts, 15s timeout per attempt)
+- Multi-consumer stream sharing via reference counting (streaming, recording, snapshots share one P2P connection)
+- 5-second grace period before stopping shared P2P stream
+- Node.js MaxListeners raised to 30 for multi-camera setups
+- fMP4 box validation (max 50MB per box) during HKSV recording
+
+### NFR-3: Compatibility
+- ESM module (`"type": "module"`, `"module": "NodeNext"`)
+- TypeScript strict mode, ES2022 target
+- PKCS1 padding workaround for Node.js 20/22 (restored natively in Node.js 24.5+)
+- Hardware codec probing at startup with graceful software fallback
+
+### NFR-4: Security
+- Encrypted credential persistence (never logged)
+- Guest account enforcement (admin account usage blocked)
+- TFA/captcha graceful handling with shutdown and re-auth prompt
+- Diagnostics archives encrypted before export
+
+---
+
+## Architecture Boundaries
+
+### homebridge-eufy-security (this plugin)
+- Accessory registration and HomeKit service mapping
+- FFmpeg transcoding pipeline
+- Configuration handling and validation
+- Plugin UI (device discovery, diagnostics, storage management)
+- accessories.json persistence for UI communication
+
+### eufy-security-client (upstream dependency)
+- Eufy cloud API authentication and communication
+- P2P connection establishment and stream management
+- Push notification and MQTT event handling
+- Device type classification and property management
+- Command execution (arm/disarm, lock/unlock, etc.)
+
+Issues must be triaged to the correct layer. The plugin communicates with the library via events (`station added`, `device added`, `property changed`, push events) and commands.
+
+---
+
+## Device Type Coverage
+
+| Category | HomeKit Services |
+|---|---|
+| Cameras | CameraRTPStreamManagement, MotionSensor, optional Switches |
+| Doorbells | Doorbell + Camera services, ProgrammableSwitchEvent |
+| Floodlights | Camera + Lightbulb services |
+| Base Stations | SecuritySystem (arm/disarm), optional manual alarm Switch |
+| Smart Locks | LockMechanism, LockManagement |
+| Entry Sensors | ContactSensor |
+| Motion Sensors | MotionSensor |
+| Smart Drop | LockMechanism (open-only), ContactSensor (package detect) |
+| Video Locks | Camera + Lock services (LockWifiVideo) |
+| Auto-Sync Station | Virtual SecuritySystem syncing multiple stations |

package/.claude/docs/hksv-recording-fix.md

@@ -0,0 +1,160 @@
+# HKSV Recording Reliability Fix
+
+**PR:** [#878](https://github.com/homebridge-plugins/homebridge-eufy-security/pull/878)
+**Branch:** `fix/hksv-recording-reliability`
+**Affects:** All cameras with HomeKit Secure Video enabled
+
+---
+
+## Problem
+
+HKSV recordings never appeared in the Apple Home timeline. Users could enable HKSV in Apple Home settings, but no recordings were captured on motion events. Two independent issues combined to make HKSV completely non-functional.
+
+## Root Cause 1: HKSV state lost on every restart
+
+### How HKSV state persistence works
+
+When a user enables HKSV for a camera in Apple Home:
+
+1. HomeKit sets the `Active` characteristic to `true` on the `CameraRecordingManagement` service
+2. HAP-NodeJS stores this in two places:
+   - The `cachedAccessories` JSON (service characteristic values)
+   - The `ControllerStorage` file (controller-specific state)
+3. On next boot, `CameraController._initWithServices()` restores services from cache
+4. `ControllerStorage.restoreController()` calls `deserialize()` to restore `recordingActive`
+
+### What was broken
+
+`CameraAccessory.configureVideoStream()` removed two controller-managed services (`CameraOperatingMode` and `DataStreamTransportManagement`) from the cached accessory before calling `configureController()`. This was added to prevent a "duplicate UUID error".
+
+However, this broke the restoration flow:
+
+```
+HAP-NodeJS CameraController._initWithServices():
+
+  IF all 3 services found in cache:
+    → Reuse cached services (preserves Active state) ✓
+
+  ELSE (any service missing):
+    → Create NEW services with Active=false ✗
+```
+
+By removing 2 of the 3 services, every restart forced the `ELSE` path, resetting `recordingActive` to `false`. HomeKit set `Active=true` once, but it was lost on every boot.
+
+### The fix
+
+Removed the stale service removal code entirely. HAP-NodeJS's `_initWithServices()` already handles service reuse through its `serializedControllers` path — the "duplicate UUID error" it was designed to prevent doesn't occur when services are properly managed by the controller.
+
+## Root Cause 2: P2P cold-start delay
+
+### The timing problem
+
+When HomeKit requests an HKSV recording after motion detection, the recording delegate must:
+
+1. Establish a P2P connection to the camera (`getLocalLiveStream()`)
+2. Start FFmpeg to transcode the stream
+3. Begin yielding fMP4 fragments to HomeKit
+
+Step 1 takes **~4.8 seconds** (observed in diagnostics). HomeKit has an approximate **5-second timeout** for the first data. This means recordings frequently failed to start in time.
+
+### How reference implementations solve this
+
+| Plugin | Approach | Prebuffer Duration |
+|--------|----------|--------------------|
+| homebridge-unifi-protect | Always-on RTSP timeshift buffer | Configurable |
+| Scrypted | Ring buffer, 2.5x HomeKit's prebufferLength | 10s default |
+| homebridge-camera-ui | Always-on prebuffer | 4s |
+
+All use prebuffering. For battery-powered Eufy cameras, always-on prebuffering is not viable.
+
+### The fix: motion-triggered P2P pre-warming
+
+When the plugin detects motion (before HomeKit even requests a recording), it proactively starts the P2P connection:
+
+```
+Motion Detected → Plugin sets MotionDetected=true on characteristic
+                → Plugin calls preWarmStream() (P2P starts in background)
+                → HomeKit receives motion notification
+                → HomeKit sends DATA_SEND OPEN → handleRecordingStreamRequest()
+                → getLocalLiveStream() returns instantly (P2P already warm)
+```
+
+A new `preWarmStream()` method on `LocalLivestreamManager` starts the P2P connection without creating a consumer fork. The stream auto-cleans up after the `STOP_GRACE_MS` (5 seconds) grace period if HomeKit doesn't request a recording.
+
+RTSP cameras are excluded from pre-warming since their stream URL is immediately available.
+
+## Additional fix: updateRecordingActive log bug
+
+`recordingDelegate.ts` line 282 had swapped log arguments:
+
+```typescript
+// Before (wrong — message as camera name, camera name as message):
+log.debug(`Recording: ${active}`, this.accessory.displayName);
+
+// After (correct):
+log.info(this.camera.getName(), `HKSV recording enabled/disabled by HomeKit.`);
+```
+
+This made HKSV state changes invisible in logs, making the root cause much harder to diagnose. Promoted to INFO level since this is a critical diagnostic signal.
+
+## HKSV Recording Flow (Architecture Reference)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     eufy-security-client                     │
+│  Device emits 'motion detected' / 'person detected' / etc.  │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    CameraAccessory.ts                         │
+│  1. characteristic.updateValue(true)  → HomeKit notified     │
+│  2. preWarmStream()                   → P2P starts warming   │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+              ┌────────────┴────────────┐
+              │                         │
+              ▼                         ▼
+┌──────────────────────┐   ┌─────────────────────────────────┐
+│  LocalLivestream     │   │  HAP-NodeJS RecordingManagement  │
+│  Manager.ts          │   │                                   │
+│  P2P connecting...   │   │  HomeKit receives MotionDetected  │
+│  Stream warming...   │   │  HomeKit decides to record        │
+│  ✓ Stream ready     │   │  DATA_SEND OPEN →                 │
+└──────────┬───────────┘   └───────────────┬───────────────────┘
+           │                               │
+           │                               ▼
+           │               ┌───────────────────────────────────┐
+           │               │  recordingDelegate.ts              │
+           │               │  handleRecordingStreamRequest()    │
+           └──────────────►│  configureInputSource()            │
+             P2P already   │    → getLocalLiveStream() instant  │
+             warm!         │  FFmpeg starts                     │
+                           │  yield fMP4 fragments → HomeKit    │
+                           └───────────────────────────────────┘
+```
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `src/accessories/CameraAccessory.ts` | Removed stale service removal; added motion-triggered pre-warming |
+| `src/controller/LocalLivestreamManager.ts` | Added `preWarmStream()` method; updated `isStreamActive()` |
+| `src/controller/recordingDelegate.ts` | Fixed `updateRecordingActive` log arguments |
+
+## User Impact
+
+### After upgrading
+
+Users who had HKSV enabled but never saw recordings should see them start working. Some users may need to:
+
+1. Restart Homebridge after the upgrade
+2. If recordings still don't appear, toggle HKSV off and on in Apple Home:
+   - Open Home app → Camera settings → Recording Options → Disable → Re-enable
+
+### Battery considerations
+
+The P2P pre-warming starts a livestream connection on every motion event. For battery-powered cameras:
+- The stream only runs for 5 seconds if HomeKit doesn't request a recording
+- This is similar to what already happens for snapshot fetching on motion
+- Impact on battery life should be minimal but is worth monitoring

package/.claude/skills/architect/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: architect
+description: Answer quick architectural questions, debug mini-issues, explore the codebase, and help improve skills and workflows. Use this skill when the user asks "how does X work", "where is Y", "why does Z happen", wants to understand code flow, trace a bug through the system, or asks about the relationship between components. Also use when the user wants to improve an existing skill or refine development workflows. This is the lightweight, exploratory counterpart to the planner -- use it for questions and small fixes, not multi-file changes.
+---
+
+# Architect
+
+You are an architectural advisor for homebridge-eufy-security. You answer questions quickly, trace code paths, debug small issues, and help refine the development workflow. You are the "thinking" mode -- fast, focused, and precise.
+
+Refer to CLAUDE.md for the full architecture and project conventions.
+
+## What you do
+
+### Codebase exploration
+
+When the user asks "how does X work" or "where is Y":
+
+1. Search the codebase (Glob, Grep) to find the relevant code
+2. Read the key files
+3. Explain the flow concisely with file:line references
+4. Draw the path through the system if it crosses multiple files
+
+Quick-reference starting points:
+
+| Question | Start here |
+|---|---|
+| Device discovery? | `src/platform.ts` -- `onStationAdded`, `onDeviceAdded`, `register_device` |
+| Streaming? | `src/controller/streamingDelegate.ts` -> `LocalLivestreamManager.ts` |
+| HKSV recording? | `src/controller/recordingDelegate.ts` |
+| Snapshots? | `src/controller/snapshotDelegate.ts` |
+| UI <-> plugin? | `src/utils/accessoriesStore.ts` -> `homebridge-ui/server.js` |
+| Arm/disarm? | `src/accessories/StationAccessory.ts` |
+| Two-way audio? | `src/utils/Talkback.ts` |
+
+### Mini-bug debugging
+
+For small, contained bugs:
+
+1. Reproduce the understanding -- what's expected vs what happens?
+2. Trace the code path from trigger to symptom
+3. Identify the root cause with file:line reference
+4. If it's a one-line fix, suggest it directly
+5. If it's bigger, recommend using the planner skill
+
+### Skill and workflow improvement
+
+When the user wants to refine skills or workflows:
+
+1. Read the current skill/workflow file
+2. Identify what's working and what's not based on user feedback
+3. Suggest specific, minimal changes
+4. Apply changes after user approval
+
+### Quick code review
+
+When asked to review code or a diff:
+
+1. Focus on correctness, not style
+2. Check the architectural boundaries (plugin vs eufy-security-client)
+3. Flag potential issues with file:line references
+4. Don't nitpick -- only flag things that could break or confuse
+
+## How to respond
+
+- Be concise. Use file:line references.
+- Show the relevant code snippet when it helps understanding.
+- If the answer requires reading more than 3-4 files, use subagents for parallel exploration.
+- If the question turns into a multi-file change request, suggest switching to the planner skill.
+- If you're unsure, say so. Don't speculate about code you haven't read.
+
+## What you don't do
+
+- Don't make multi-file code changes (use planner -> developer)
+- Don't run builds or lint (use QA skill)
+- Don't create PRs or push code (use the git workflow directly)
+- Don't write lengthy essays -- keep answers tight and actionable