@homebridge-plugins/homebridge-eufy-security 4.6.0-beta.2 → 4.6.0-beta.21

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.enc`
+- Always check archive completeness before analysis -- missing runtime logs means the plugin wasn't running
+- Check if debug mode is enabled (`enableDetailedLogging`); if disabled, ask the user to enable it and re-export
+- 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/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

package/.claude/skills/developer/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: developer
+description: Execute code changes following an approved plan or direct user instructions. Use this skill when the user says "implement", "code it", "go ahead", "execute the plan", or when transitioning from the planner skill after approval. Also use for direct coding tasks where the user provides clear, specific instructions. This skill writes clean, correct code respecting all project conventions.
+---
+
+# Developer
+
+You are a code execution agent for homebridge-eufy-security. You write code that is clean, correct, and follows every project convention. You either execute an approved plan from the planner skill, or implement direct user instructions.
+
+Follow all conventions in CLAUDE.md (ESM imports, lint, architecture patterns, code style, git workflow).
+
+## Before writing any code
+
+1. **Read first**: Read every file you intend to modify. Understand existing patterns before touching them.
+2. **Check the plan**: If a plan was approved, follow it exactly. If you spot an issue with the plan during implementation, stop and flag it -- don't silently deviate.
+3. **Branch check**: Verify you're on the correct branch per CLAUDE.md git workflow.
+
+## Implementation workflow
+
+### Step 1 -- Write the code
+
+Make changes file by file, following the plan order. For each file:
+- Use the Edit tool for modifications (not Bash with sed/awk)
+- Use Write only for new files
+- Keep changes minimal and focused
+- Don't add features beyond what was requested
+- Don't refactor surrounding code while fixing a bug
+
+### Step 2 -- Self-review
+
+After all changes are made, re-read each modified file to verify:
+- No syntax errors
+- Imports use `.js` extensions
+- No accidental duplicate code
+- Changes match the plan
+
+### Step 3 -- Verify
+
+```bash
+npm run lint
+npm run build
+```
+
+If either fails, fix the issue immediately. Do not commit code that doesn't lint or build.
+
+### Step 4 -- Commit
+
+Follow the git workflow from CLAUDE.md. Stage each logical change individually.
+
+## When things go wrong
+
+- **Lint failure**: Fix the warning. Don't disable the rule.
+- **Build failure**: Read the error. If it's a type error, trace it back. If it's an import error, check `.js` extensions.
+- **Plan doesn't work**: Stop. Explain what you found. Don't improvise a workaround without user approval.
+- **Unclear requirement**: Ask. Don't guess.

package/.claude/skills/new-device-support/SKILL.md

@@ -96,37 +96,25 @@ case <type_number>: return '<image_large>.png';
 Execute the plan. Key implementation notes:
 
 - **Property mapping**: Use the output from `map-properties.mjs` (Phase 1) as the primary guide. When multiple property constants match the same `param_type` (e.g. `DeviceWatermarkProperty` vs `DeviceWatermarkSoloWiredDoorbellProperty`), pick the variant used by the closest existing device. Check the "Used by DeviceTypes" column in the script output.
+- **Companion custom properties**: Some properties have required companions with `custom_*` keys that never appear in raw device data (they're populated at runtime). The script detects these and marks them with `⚠ companion`. Always include them — omitting a companion breaks functionality silently. Key pairs: `DeviceRTSPStream` → `DeviceRTSPStreamUrl`, `DeviceWifiRSSI` → `DeviceWifiSignalLevel`, `DeviceCellularRSSI` → `DeviceCellularSignalLevel`.
 - **Insert in order**: When adding to enums, switch statements, or `if` chains, maintain numeric ordering by device type number.
 - **Audio recording property**: Different device families use different audio recording property constants (e.g. `DeviceAudioRecordingProperty`, `DeviceAudioRecordingStarlight4gLTEProperty`). Match the closest existing device.
-- **No Co-Authored-By**: Do not add co-author lines to commits.
 
 ## Phase 4 — Build & Lint Verification
 
-Run these in parallel:
-```bash
-cd eufy-security-client && npm run build
-cd homebridge-eufy-security && npm run build
-```
-
-Then verify lint:
-```bash
-cd eufy-security-client && npm run lint
-cd homebridge-eufy-security && npm run lint
-```
-
-Note: eufy-security-client lint may fail due to a pre-existing `jiti` library issue unrelated to our changes. The TypeScript build succeeding is sufficient validation.
+Run build and lint for both repos. Note: eufy-security-client lint may fail due to a pre-existing `jiti` library issue unrelated to our changes — the TypeScript build succeeding is sufficient validation.
 
 ## Phase 5 — Git & PR
 
-### eufy-security-client
+Follow CLAUDE.md Git Workflow for commit messages, branch naming, and PR body format. This skill creates **two PRs** across repos:
+
+### eufy-security-client (cross-fork)
 
-1. Discard any unrelated changes (e.g. `package-lock.json`)
-2. Sync develop with upstream: `git fetch upstream && git checkout develop && git merge upstream/develop`
-3. Create branch: `git checkout -b feat/<device-slug>`
-4. Stage only relevant files (images (should match the `<device-slug>`), `src/http/types.ts`, `src/http/device.ts`, `src/push/service.ts`, `docs/supported_devices.md`)
-5. Commit: `git commit -m "feat: add <Device Name> (<Model>, type <number>) support"`
-6. Push: `git push origin feat/<device-slug>`
-7. Create cross-fork PR:
+1. Discard unrelated changes (e.g. `package-lock.json`)
+2. Sync develop: `git fetch upstream && git checkout develop && git merge upstream/develop`
+3. Branch: `git checkout -b feat/<device-slug>`
+4. Stage only: images, `src/http/types.ts`, `src/http/device.ts`, `src/push/service.ts`, `docs/supported_devices.md`
+5. Cross-fork PR:
    ```bash
    gh pr create --repo bropat/eufy-security-client --base develop \
      --head lenoxys:feat/<device-slug> \
@@ -136,26 +124,9 @@ Note: eufy-security-client lint may fail due to a pre-existing `jiti` library is
 
 ### homebridge-eufy-security
 
-1. Branch from the current beta branch (check with `git branch`): `git checkout -b feat/<device-slug>`
+1. Branch from current beta: `git checkout -b feat/<device-slug>`
 2. Stage: `homebridge-ui/public/utils/device-images.js` + any added image
-3. Commit: `git commit -m "feat: add <Device Name> (<Model>, type <number>) device image mapping"`
-4. Push: `git push origin feat/<device-slug>`
-5. Create PR:
-   ```bash
-   gh pr create --repo homebridge-plugins/homebridge-eufy-security \
-     --base <beta-branch> \
-     --title "feat: add <Device Name> (<Model>, type <number>) device image" \
-     --body-file /tmp/pr-body-<branch>.md
-   ```
-
-### PR body format
-
-Write PR bodies to `/tmp/pr-body-<branch>.md` files. Include:
-- `## Summary` — bullet points describing the changes
-- Cross-references: `Closes homebridge-plugins/homebridge-eufy-security#<issue>` in the client PR, `Closes #<issue>` in the plugin PR
-- `Depends on bropat/eufy-security-client#<pr>` in the plugin PR
-- `## Test plan` — checklist of verification steps
 
-### Link the issue
+### Cross-referencing
 
-After both PRs are created, update both PR bodies so they reference the issue with closing keywords.
+After both PRs are created, update both bodies so they reference each other.