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 their status labels (Project v2 was dropped on 2026-08-14, #139). Companion documents: UX-MODES.md (interaction model); the historical engineering direction is archived in legacy/docs/ROADMAP.md. 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 lives only in git history (removed by #678).

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 (all 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 writer-only tools and must never leak interactions into View (established by UX-MODES; lock guard, inert openings, no drag in View). By default only administrators are writers; an installation may explicitly let ordinary household users edit, but Home Assistant's system-read-only group never becomes a writer. Authenticated View deliberately shares the complete spatial plan and represented-device configuration with household members rather than pretending to be an entity-by-entity privacy boundary. 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 (SVG/PNG/JPG/WebP) or 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, three editors (plan, devices, background), drag/resize, merge/split, multi-client live sync, optimistic locking	Closed
J7	"Is my Zigbee mesh healthy here?" — LQI badges, per-room average/fill and opt-in direct-neighbour links for one hovered device	Closed (spatial diagnostics; no persistent full-mesh graph)

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: the English user guide covers less than the Russian one (#668).

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

• Person/presence shown in rooms (classic floorplan ask; pure J1). Started on the owner's request with mmWave radar presence, #485 (docs/RADAR.md); anything beyond it stays here.

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. A narrow owner-approved exception for #485 allows explicit HA-admin-confirmed creation/removal of House Plan's own derived room presence and estimated-count entities only; it does not create automations or rename, reassign or disable source entities. Ordinary radar setup has no implicit provisioning side effect.
• History, graphs, statistics → recorder/history cards. We show now, not then. A narrow exception approved for #485, with defaults confirmed on 2026-09-08, permits local spatial radar setup/occupancy analysis: explicitly started observation runs of at most 24 hours with raw points expiring after 24 hours, and a separately enabled day/week heatmap containing coarse aggregate cells for at most seven days. Each aggregate collection run also lasts at most 24 hours. History/collection controls require House Plan editing permission; no automatic start, renewal or restart, continuous multi-day collection, cloud upload or personal identity tracking. Ordinary View remains current-only. This does not authorize a general history dashboard.
• 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.
• General CAD, architectural drafting and construction-document tooling → specialised applications. A narrow read-only exception approved on 2026-08-15 and scoped on 2026-09-07 for #53 exports the current canonical space as a single print-ready PDF. It introduces no second geometry model, drawing tools or all-spaces document workflow; its purpose is to hand the already maintained House Plan geometry to an installer, insurer or renovation contractor.
• A general dashboard framework (menus, popups, theming engine) → Bubble Card, Dwains and friends. A narrow exception approved on 2026-09-03 for #437 is a configurable read-only summary overlay accompanying the spatial plan: named groups of current HA states and three built-in values (represented device count, clean room-floor area, date/time). It adds no arbitrary cards, formulas, history, device actions or HA administration; shared GUI configuration and per-screen visibility do not turn it into a general dashboard builder.

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. Three built-in editors (plan, devices and background) 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.