diff --git a/docs/competitive-feature-scope.md b/docs/competitive-feature-scope.md new file mode 100644 index 0000000..a6c3c7c --- /dev/null +++ b/docs/competitive-feature-scope.md @@ -0,0 +1,140 @@ +# Competitive Feature Scope — vs Home Assistant & Homebridge + +Draft scope. Last updated: July 2026. + +## The framing problem + +Home Assistant and Homebridge win on **breadth and control density**: thousands of +integrations, arbitrary automations, and (for Homebridge) exposing non-HomeKit +hardware into the Apple ecosystem. Lumen's own `ROADMAP.md` is explicit that we +**do not compete on toggle density or integration count**, and must **never add an +auto-apply-without-confirmation mode**. The moat is calm + explainability + consent. + +So "compete with Home Assistant and Homebridge" cannot mean "clone them." It means +closing the two gaps where a prospective user genuinely *can't use Lumen at all* +today — and closing them **on Lumen's terms** (explained, consented, calm). + +Those two gaps map cleanly onto the two competitors: + +| Competitor | What it gives users | Lumen's gap today | +|-----------|--------------------|-------------------| +| **Homebridge** | Control devices Apple Home can't see | Lumen only speaks HomeKit (+ fire-and-forget IR) | +| **Home Assistant** | Rich automations: time, sensor, conditional triggers | `Scene` has one trigger axis — geofence arrival/departure | + +Everything below is filtered so it strengthens the moat instead of diluting it. + +--- + +## Tier 1 — the two gaps that lock users out + +### 1. A second real bridge: local-LAN device support (the Homebridge move) + +**Why:** Today, a Shelly relay, a Tasmota/ESPHome switch, a LIFX bulb on LAN, or a +Tuya device that never made it into Apple Home is invisible to Lumen. This is the +single most common "I can't switch to your app" objection Homebridge exists to solve. + +**Why it's cheap architecturally:** the app is already multi-bridge. +`DeviceService.registeredBridges: [BridgeID: any SmartHomeBridge]` routes every +action by `device.bridgeID` (`DeviceService.swift:38-51`); `BridgeID` is just a +string; `registerBridge` wires a new bridge into the `DeviceStateStore` state +stream. HomeKit is not special — it is simply the first bridge registered. The IR +layer already proves the "second ecosystem behind a transport seam" pattern +(`RemoteService` + `IRTransport`). + +**Scope:** add a `LocalNetworkBridge` conforming to `SmartHomeBridge`, driving devices +that expose a **local HTTP/REST or simple socket API** — no cloud, no account, keeps the +local-first posture. Reuse the existing capability protocols (`OnOffCapability`, +`BrightnessCapability`, …) so these devices render in the exact same UI with zero +view changes. Start with one or two well-documented local protocols (Shelly Gen2 RPC +and generic REST-on/off are good first targets) rather than a plugin marketplace. + +**Moat fit:** neutral-to-positive. More reachable devices, same consent surfaces. No +change to the execution/approval pipeline. + +**Non-goals:** no cloud-polling integrations, no arbitrary plugin runtime (that is +Homebridge's maintenance-burden model, not ours), no Matter commissioning here (already +Roadmap Phase 5, and Matter already arrives via HomeKit). + +### 2. Time & schedule triggers for scenes (the Home Assistant move) + +**Why:** "Turn the porch light on at sunset," "Wind-down scene at 9pm" — schedule is +the #1 automation type in Home Assistant and the most-requested thing a geofence-only +model can't express. `Scene.geofenceTrigger` is the *only* trigger today. + +**Scope:** generalize the single `geofenceTrigger` enum into a small set of +composable triggers. Add `TimeTrigger` (fixed time-of-day; sunset/sunrise as a +fast-follow once we have `Home` coordinates from Roadmap Phase 1). Keep the pure +routing pattern already used by `SceneService.scenesMatching(event:in:)` — a +scheduled poll analogous to the geofence poller (`SceneService.monitoringTask`). + +**The consent question (must resolve before building):** does a scheduled scene fire +directly, or surface a suggestion? A defensible reading of the moat: **setting a +schedule *is* the consent** — the user pre-authorized this exact scene at this exact +time, explicitly, ahead of time. That is categorically different from the forbidden +"auto-apply on a hunch." Recommend: scheduled scenes fire directly **but** post an +explainable notification ("Wind-down ran at 9:00 PM — you scheduled this. Undo?"), +preserving explainability and reversibility. This needs a `ROADMAP.md` sign-off since +it touches the auto-apply boundary. + +--- + +## Tier 2 — turn latent capability into explainable automation + +These use machinery Lumen already has; they deepen the moat rather than chase parity. + +### 3. Sensor-driven suggestions + +`SensorObservationService` already ingests motion/contact `AsyncStream`s from every +capable device — but only **records** them into a ring buffer. Feed those signals into +`SuggestionEngine` so "motion in the hallway after dark → suggest Path Lighting" +becomes a scored, explainable suggestion. This is Home Assistant-style reactivity +delivered the Lumen way: it *suggests and asks*, it doesn't silently fire. Purely +additive to the existing scored layer; every factor stays human-readable. + +### 4. Conditional / multi-signal rules (explainable rule builder) + +Home Assistant's power is trigger **+ condition + action**. Lumen can offer a calm, +readable version: "When [motion] **and** [it's evening] **and** [I'm home] → suggest +[Cozy]." The scoring layer already combines time-of-day, presence, and habit signals; +this exposes that combination as a user-authorable rule while keeping the one-sentence +explanation per factor. Deliberately *not* a YAML/DSL — a guided, low-cognitive-load +builder. + +### 5. Calm home history ("what happened today") + +`ExecutionEvent` is already persisted (schema V2). Surface it — plus in-memory +`SensorEvent`s — as a gentle daily timeline, not Home Assistant's dense logbook. This +directly serves the trust/explainability mission: users see what Lumen did and why, +after the fact. Read-only, no new schema for the execution side. + +--- + +## Tier 3 — parity/adjacent, lower priority + +- **Richer notifications** — `NotificationService` exists but only fires on geofence. + Alert on "contact sensor left open," "unusual late-night motion." Consent-neutral. +- **Capability breadth** — no fan/speed, garage door, cover tilt, or thermostat-mode + UI beyond the `HVACMode` enum, no media transport. Each is an incremental capability + add (`DeviceCapability` + a renderer), not architectural work. Prioritize by what + Tier-1 bridges actually expose. +- **Config export / backup** — Home Assistant users expect their setup to be portable. + A local-first export of homes/rooms/scenes reinforces "your data is yours." +- **Matter in-app commissioning** — already Roadmap Phase 5; noted here for completeness. + +--- + +## Explicit non-goals (protect the moat) + +- No auto-apply-without-confirmation mode, even as a power-user opt-in (per `ROADMAP.md`). +- No plugin/add-on runtime or marketplace (Homebridge's maintenance model). +- No cloud-account integrations that break the local-first posture. +- No dashboard/entity-grid density race (Controller-for-HomeKit's game, not ours). + +## Recommended sequence + +1. **Tier 1.2 (time/schedule triggers)** — highest user value, self-contained, but land + the `ROADMAP.md` consent sign-off first. +2. **Tier 1.1 (LocalNetworkBridge)** — highest strategic value vs both competitors; + larger surface, so scope to one local protocol end-to-end before generalizing. +3. **Tier 2.3 (sensor-driven suggestions)** — cheap, on-brand, reuses the scored layer. +4. Everything else as pull demand dictates.