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](https://github.com/Matysh/houseplan-card/issues) and their
status labels (Project v2 was dropped on 2026-08-14, #139). 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 (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](https://github.com/Matysh/houseplan-card/issues/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](https://github.com/Matysh/houseplan-card/issues/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](https://github.com/Matysh/houseplan-card/issues/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](https://github.com/Matysh/houseplan-card/issues/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](https://github.com/Matysh/houseplan-card/issues/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](https://github.com/Matysh/houseplan-card/issues/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](https://github.com/Matysh/houseplan-card/issues/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.