houseplan-card/docs/SCOPE.md

Product scope — what House Plan is and is not

Fixed with the owner on 2026-07-22. This document is a guard rail: features are built, improved and accepted only if they serve a job listed here. When a new idea appears, first find its row in this file; if there is none — it belongs to HA core, to another card, or nowhere. The current order of work lives only in GitHub Issues and the linked Project v2. Companion documents: ROADMAP.md (historical engineering direction), UX-MODES.md (interaction model). TOUCH-SUPPORT.md fixes the input-support contract: touch is a guaranteed View surface, while every editor is desktop-first and best effort on touch. The old market snapshot is archived at legacy/docs/PRODUCT-2026-07-05.md.

Mission

House Plan is the spatial "at a glance + quick act" layer for a Home Assistant home. Upload or draw a floor plan, outline rooms bound to HA areas, and the home's devices appear on a live, tappable map: states, climate, alerts, guarded quick actions. Setup is GUI-only — no Inkscape, no YAML, no external editors. Everything that is not "look at the home spatially and act on the obvious" is somebody else's job.

Target audience

Persona	Role	Surface
Home admin (primary)	HA enthusiast, house/large flat, 20–200 devices, several floors; sets up and maintains the plan	Desktop browser (both editors live here)
Household members	Non-technical; consume the plan daily, never edit	Wall tablet (kiosk), phone (companion app)
Guests / kiosk	View-only glance at the home	Wall tablet

Design consequence: View mode is the product for two of the three personas. Editors are admin-only tools and must never leak interactions into View (established by UX-MODES; lock guard, inert openings, no drag in View). The desktop browser with mouse/keyboard is the reference and recommended editing environment. Editor parity on touch is outside the product guarantee; deliberate degradation is allowed under TOUCH-SUPPORT.md.

Core user jobs — the component must close these

#	Job (user's words)	Status
J1	"Show the whole home and what's happening right now" — live spatial overview: device states, room fills (light/temp/LQI), values, multi-floor tabs	Closed
J2	"Something is wrong — show me where" — leak/smoke/gas pulse, open doors/windows, unlocked locks, red dot on devices HA added silently	Closed
J3	"Let me act on the obvious right from the plan" — tap-to-toggle for safe domains, info cards, guarded lock action	Closed
J4	"From zero to a working plan in one evening, no Inkscape/YAML" — image/PDF/draw, floors-import wizard, room polygons bound to areas, filtered auto-placement, editable icon rules	Closed; onboarding polish is partial (no registry-driven room suggestions)
J5	"Room climate at a glance" — per-room temperature/humidity, comfort-range fills, room-card metrics	Closed
J6	"Keep the plan true as the home evolves" — new-device flag, two editors, drag/resize, merge/split, multi-client live sync, optimistic locking	Closed
J7	"Is my Zigbee mesh healthy here?" — LQI badges, per-room average, LQI fill	Closed (kept deliberately: cheap, spatial by nature, no in-plan competitor)

Partially covered — improvement backlog stays inside these

• Touch ergonomics of the editors: editors are desktop-first by product decision. Touch support is best effort and may remain partial; spend on it only when the improvement is cheap and does not complicate the desktop model.
• Value display: single current value per device; units/precision follow HA formatting only.
• Accessibility: prefers-reduced-motion only; no keyboard navigation in editors, no ARIA labelling of the plan.
• Docs/screenshots: README predates the two-editor redesign.

Known gaps that fit the mission (build only on owner's request)

• Person/presence shown in rooms (classic floorplan ask; pure J1).

The lock invariant, stated precisely (review CR-1)

No lock or alarm panel is ever actuated by a tap on the plan: icons, lock badges, marker.controls[] and the device card all refuse (resolveToggleIntent secure targets, isControllable, _cardToggle). The universal Toggle state option may be selected and saved, but its hint explicitly reports a secure no-op and the click path makes no service call. There is exactly one sanctioned actuation surface: the labeled Unlock/Lock button inside an opened door card, which additionally confirms before unlocking. That is a product decision (2026-07-22), not an oversight — but it means the invariant is "never by accident", not "never at all". Any new actuation path must either refuse locks or be added to this paragraph.

• Plan-level "security glance": one badge for "all locked / N open" (J2).
• Threshold colouring for room-card metrics (J5).

Standing rule: never delete a user's file on an inference

Fixed with the owner on 2026-07-28, after automatic collection removed two detached floor plans. The component may delete a file only when the user's action says so — replacing a plan, removing an attachment, deleting a device. "Nothing points at this any more" is not such an action: detaching a plan is one click and reversible, and the editor tells the user the file stays.

The asymmetry is the whole argument. Wasted disk is visible, cheap and reversible; a deleted file is none of those. Where the evidence is weak, keep the file — and if a future version wants to reclaim that space, it asks.

Out of scope — never build, point users to the right tool

• Automations, scenes, scripts, notifications → HA core.
• Device/entity administration (rename, reassign area, disable) → HA registry UIs. We read the registry, we never manage it.
• History, graphs, statistics → recorder/history cards. We show now, not then.
• Camera streams, media controls → their own cards; our more-info opens HA's.
• Energy monitoring/analytics → HA Energy.
• Photorealistic rendering, a free 3D camera, a separate 3D model and 3D furniture/interior editing → niche tools (easy-floorplan et al.); we are a live spatial map, not an interior editor. A narrow exception approved for #89 is a deterministic 2.5D presentation of the existing canonical plan: the same J1/J2/J3 state, actions and geometry, with no second model and no free camera.
• A general dashboard framework (menus, popups, theming engine) → Bubble Card, Dwains and friends.

Excess-functionality audit (2026-07-22)

• Device metadata: links & PDF manuals — not spatial, but tiny, server-side, and used in real installs. Verdict: keep, frozen (no growth).
• Virtual devices — placeholders for not-yet-installed hardware; serves J6. Verdict: keep, frozen.
• LQI diagnostics — promoted to J7 (differentiator), not excess.
• Nothing found that warrants removal; the mode redesign already moved every interaction to where it belongs.

The component in one breath (README/HACS copy)

House Plan turns your Home Assistant into a live map of your home. Upload a plan image (or draw one), outline rooms and bind them to HA areas — your devices appear in place, automatically, with live states. Glance at the wall tablet: what's on, what's open, what's too cold, what's leaking, what's new. Tap to act — safely: locks never toggle by accident. Two built-in editors (plan and devices) mean no Inkscape, no YAML, no external tools — ever.

Tasks it closes: whole-home live overview · spatial alerts (leak/smoke/open/ unlocked/new device) · safe quick actions · per-room climate · Zigbee mesh health · zero-to-plan GUI onboarding · keeping the plan true over years.

Where users are: Telegram chat https://t.me/ha_houseplan (support, feature signals, screenshots) — treat it as the primary source of field feedback.

Pains it removes: hand-crafted SVG + YAML floorplans · entity-list dashboards that hide where things happen · silent device sprawl · accidental toggles of security devices · per-device dashboards that non-technical family members can't read.