docs: full project audit pack for agents (market, quality, gaps)

Add docs/AUDIT*.md covering competitive landscape (easy-floorplan 11→430★),
implementation quality, functional integrity, and P0–P3 recommendations.
Refresh PRODUCT.md competitor claim and point STATUS watchlist at the pack.

Co-authored-by: Matysh <Matysh@users.noreply.github.com>

docs/AUDIT-FUNCTIONAL.md

@@ -0,0 +1,154 @@
+# Audit — functional integrity & gaps
+
+> Snapshot: **2026-08-05**, product **v1.58.0**.
+> Cross-check of claimed surface (README / STATUS / SCOPE) against code and
+> tests. Mission lens: SCOPE.md — *spatial at-a-glance + quick act*.
+
+## 1. Mission fit
+
+SCOPE personas:
+
+| Persona | Primary mode | Fit |
+|---|---|---|
+| Home admin | Plan / Devices / Background editors | Strong — full geometry + marker tooling |
+| Household members | View | Strong — tap toggles, room cards, glow/climate |
+| Guests / kiosk | View + `kiosk: true` | Strong — editors blocked, swipe/cycle |
+
+Jobs J1–J7 are marked **Closed** in SCOPE; J4 (onboarding) still **partial**
+(floors-import exists; registry-driven room *suggestions* do not). That matches
+code reality.
+
+**Systematicity grade: high.** Features hang off a coherent model:
+
+- spaces → rooms (polygons) → derived walls → openings
+- markers bound to device/entity/virtual → layout points
+- settings tiers: global → space → room → device
+- View is the product; editors are admin-colored frames (UX-MODES)
+
+Excess features (PDF manuals, virtual devices, LQI) are consciously **kept /
+frozen** rather than deleted — unusual and correct for a shipping tool.
+
+## 2. Claim ↔ code matrix
+
+| Feature area | Claimed | Implemented | Tested | Notes |
+|---|---|---|---|---|
+| One HACS package (integration + card) | ✓ | ✓ | CI hacs/hassfest | Matches |
+| GUI room markup (no SVG/YAML) | ✓ | ✓ | smokes + logic units | Matches |
+| Doors/windows + lock invariant | ✓ | ✓ | smoke_lock_*, logic | CR-1 held |
+| Islands / merge / split / open_to | ✓ | ✓ | units + smokes | Matches |
+| Room resize | ✓ | `resize.ts` | units + smokes | Matches |
+| Decor + backdrop transform | ✓ | ✓ (v1.58) | backdrop tests/smokes | Paper = room contours |
+| Infinite / square canvas | ✓ | ✓ | canvas smokes | Matches CANVAS.md |
+| Align-to-grid | ✓ | `align-grid.ts` | units | Matches |
+| Auto devices by HA area | ✓ | `devices.ts` | units | Matches |
+| Explicit hide-from-plan | ✓ | ✓ | smokes | FILTERING.md |
+| Editable icon rules | ✓ | ✓ | — | Matches |
+| Tap: info / more-info / toggle / run / cover | ✓ | ✓ | logic + smokes | Security model intact |
+| Glow + door sectors | ✓ | ✓ | smokes | Island light block = known limit |
+| Temp / LQI / light fills | ✓ | ✓ | units/smokes | Matches |
+| Room cards + per-room settings | ✓ | ✓ | smokes | Matches |
+| Kiosk | ✓ | ✓ | smokes | Matches |
+| Vacuums + server trails | ✓ | `vacuum.ts` + `trails.py` | units + smokes | Display-only (intentional) |
+| Sun / daynight / wedges | ✓ | `sun.ts` | units + smokes | Matches |
+| `houseplan-space-card` | ✓ | ✓ | smokes | Matches |
+| Signed content + SVG sandbox | ✓ | ✓ | HA tests + smokes | Matches |
+| en/ru i18n | ✓ | ✓ | key-parity test | Matches |
+| Floors-import wizard | ✓ | ✓ | — | Exists; suggestions gap below |
+| Registry room suggestions | PRODUCT / J4 | **Partial / missing** | — | Gap |
+| Music notes / TV ripples | UX backlog | **Absent** | — | Intentional not-planned |
+| Furniture / wall CAD | competitor feature | **Absent** | — | Non-goal |
+| Vacuum commands | user ask often | **Absent** | — | VACUUM.md non-goal |
+| Cloud sync | — | **Absent** | — | Non-goal |
+
+**Integrity conclusion:** marketed surface and shipped surface align unusually
+well. The main integrity risks are **docs drift** (ARCHITECTURE/UX-MODES/PRODUCT)
+and **auth UI↔API default mismatch** (see AUDIT-QUALITY), not phantom features.
+
+## 3. Cross-cutting integrity themes
+
+### 3.1 Coordinate & geometry story — coherent after evolution
+
+Legacy fixed pixel canvas → normalized square → infinite canvas with bounds.
+Migrations + `geometry/repair` + dual-store `geom_pending` show the team treats
+coordinate changes as product-critical (correct). Frontend `space-geometry.ts`
+and backend `validation.py` intentionally mirror limits (±5000) — two sources of
+truth, but tested.
+
+### 3.2 Security story — mostly coherent
+
+| Surface | Policy | Coherent? |
+|---|---|---|
+| Lock / alarm from plan icon | Never actuate | Yes — tested |
+| Lock via door-card button | Explicit labeled control | Yes — SCOPE CR-1 |
+| SVG plans | Sandbox CSP + signing | Yes |
+| Config/layout writes | `may_write` | **Split** with UI admin gate |
+| `run` tap | automation/script/scene only + optional confirm | Yes |
+
+### 3.3 Multi-client story — mostly coherent
+
+Config writes: CAS + write chain. Layout point updates: rev bumps but **no**
+conflict surface — fine for one editor, weak for two tablets dragging at once.
+
+### 3.4 Filtering story — cleaned up
+
+Old hardcoded “dacha DNA” filters → editable icon rules + explicit hide flags
+(v1.51). Documented in FILTERING.md. Good systematic cleanup.
+
+## 4. Gaps (build only with intent)
+
+### In-mission polish (SCOPE already lists most)
+
+| Gap | Persona impact | Notes |
+|---|---|---|
+| Registry-driven room suggestions | Admin first-run | J4 partial; biggest *product* unlock left |
+| Touch ergonomics of editors | Admin on tablet | Partial |
+| Value-display richness | Household | Partial |
+| a11y beyond `prefers-reduced-motion` | All | Keyboard/ARIA weak |
+| Plan-level security glance (“N open / all locked”) | Household / kiosk | SCOPE known gap |
+| Person / presence in rooms | Household | SCOPE known gap; presence ripples exist at marker level |
+| Threshold colouring for room metrics | Household | SCOPE known gap |
+| README / screenshot lag vs redesign | Adoption | Distribution, not function |
+
+### Engineering gaps that feel like product bugs
+
+| Gap | Why it matters |
+|---|---|
+| Default `admin_only=False` while UI hides editors from non-admins | Non-admin can still mutate via raw WS — surprise vs household persona |
+| Opening-measure magnet placement flake under pinned Chromium | One smoke red; pixel-precision path |
+| Demo.html needs hass nudge / F5 for icons | Harness quirk; confuses manual demo in a raw browser |
+
+### Explicit non-gaps (do not “fix” by building these)
+
+- 3D / glb
+- Furniture / wall drawing (easy-floorplan territory)
+- Vacuum start/zone commands
+- History graphs, cameras, energy
+- Cloud collaboration
+- Becoming a general dashboard framework
+
+## 5. Systematicity scorecard
+
+| Question | Answer |
+|---|---|
+| Is there one mental model? | Yes — spaces/rooms/markers/settings tiers |
+| Do modes prevent tool leakage? | Mostly — UX-MODES + kiosk hard-block; View is default |
+| Are overrides predictable? | Yes — more specific settings win |
+| Do security rules have a single owner? | Tap: `resolveTapAction`. Write: `may_write` (UI duplicate — debt) |
+| Are frozen excesses documented? | Yes — SCOPE excess audit |
+| Is the roadmap still pointing at the mission? | Phase 8–10 are quality/distribution; Phase 9 leftovers are registry/docs — aligned |
+
+**Grade: A− for functional systematicity.** The product feels designed, not
+accreted — with the structural exception of the Lit shell size (quality debt,
+not a feature-model debt).
+
+## 6. Suggested integrity checks for future agents
+
+Before merging a feature:
+
+1. Does it serve J1–J7 or a SCOPE “known gap”? If neither → reject or rewrite.
+2. Does it introduce a second policy for taps, writes, or file deletion? → fold
+   into `resolveTapAction` / `may_write` / collection rules.
+3. Does it need a migration? → dual-store / repair path, not silent reshape.
+4. Is it tested at the right layer? Pure math → `npm test` / pytest; pointer UX
+   → smoke with `check`/`finish`; never a smoke that always exits 0.
+5. Dual CHANGELOG + STATUS/ARCHITECTURE/TESTING updates in the **same** commit.

docs/AUDIT-MARKET.md

@@ -0,0 +1,112 @@
+# Audit — market potential & competitors
+
+> Snapshot: **2026-08-05**. Star counts via GitHub API the same day.
+> Supersedes the competitor table in `PRODUCT.md` (2026-07-05) until that
+> file is rewritten. Re-verify numbers before any public claim.
+
+## 1. Demand shape
+
+| Signal | Evidence |
+|---|---|
+| Persistent pain | HA Community “Floorplan” category; “100% Floorplan UI” mega-thread (500k+ views historically) |
+| 2025–2026 wave | Multiple GUI floorplan projects launched within months (easy-floorplan May 2026, Padraigggs Mar 2026, House Plan Jul 2026, plus older SVG/YAML tools) |
+| Audience | Enthusiasts with wall tablets / panel dashboards — **niche but sticky** |
+| Adjacent proof | Bubble Card (~4.4k★) shows polished GUI Lovelace cards can go quasi-mainstream; ha-floorplan (~1.6k★) with a hostile workflow shows a demand floor for *spatial* UIs |
+
+**Verdict:** demand is real. The bottleneck is not “do people want a plan?” —
+it is “which GUI-first story wins attention before HA core ships something
+spatial.”
+
+## 2. Competitive landscape (2026-08-05)
+
+| Project | ★ | Updated | Approach | Overlaps us | Where we still win | Where they win |
+|---|---:|---|---|---|---|---|
+| [ha-floorplan](https://github.com/ExperienceLovelace/ha-floorplan) | **1584** | 2026-07 | Hand SVG + YAML/TS rules | Visualization power | Zero Inkscape/YAML barrier; shared server config | Max customization, mature ecosystem, contributors |
+| [easy-floorplan](https://github.com/nicosandller/easy-floorplan) | **430** | 2026-08-04 | In-card draw walls/furniture/devices | **Direct peer** — GUI, no YAML | HA **integration** + `.storage`, area-bound rooms, auto devices, vacuums/sun/glow/kiosk, quality-scale CI | Furniture drawing, faster growth, press (DE blogs), simpler “draw a house” story |
+| native `picture-elements` | built-in | — | % coords in YAML | Overlay icons on image | Editor + zones + shared layout | Zero install, official |
+| native Areas / Home dashboard | built-in | evolving | Grid by area/floor | “At a glance” home | **Spatial** plan | First-party discoverability |
+| [Padraigggs interactive floorplan](https://github.com/Padraiggg/Padraigggs-ha-interactive-floorplan) | 42 | 2026-04 | Editor + viewer cards, push to dashboard YAML | GUI editor | Server store, room polygons↔areas, overlays | Polygon light zones, camera animations, YAML export |
+| [zigbee-floorplan-card](https://github.com/TheLarsinator/zigbee-floorplan-card) | 73 | 2026-04 | LQI over image | LQI overlay | Full product, not single-purpose | Narrow clarity |
+| Dwains / Bubble Card | 2k / 4.4k | — | Dashboards / card kits | GUI quality bar | Spatial niche | Distribution, brand |
+| **House Plan** (us) | **21** | 2026-08-05 | Integration + card, room markup, server layout | — | See §3 | Traction, HACS default pending |
+
+### Critical change since PRODUCT.md (2026-07-05)
+
+`easy-floorplan` was listed at **11★ / immature**. One month later it is
+**≈430★**, actively released (v0.8.x), and getting third-party blog coverage.
+That collapses the old claim that the GUI-floorplan niche is “currently
+unoccupied.” The niche is now a **race**, and they are ahead on attention.
+
+House Plan is **not** the same product: we refuse furniture/wall CAD
+(SCOPE / ROADMAP non-goal) and instead ship a **storage integration**,
+area-linked rooms, multi-client layout, and curated overlays. That moat is
+real — but only if users *find* us and understand the difference in one
+demo GIF.
+
+## 3. Our moat (still valid)
+
+Nobody else currently combines all of:
+
+1. **Server-side config** — HA integration, `.storage`, optimistic `expected_rev`,
+   live multi-client sync, survives dashboard YAML edits.
+2. **In-card room polygon editor** bound to HA **areas** → auto device placement.
+3. **Curated overlays** — glow pools, temp/LQI fills, sun wedges, vacuum trails,
+   cover morph, lock invariant.
+4. **Operational maturity** — quality_scale.yaml, 4-layer tests, signed content +
+   SVG CSP, diagnostics/repairs/system_health, dual en/ru docs.
+
+Card-only peers store config in Lovelace YAML (or push into it). That is fine
+for one admin laptop; it is weaker for family tablets and multi-user homes —
+exactly our persona split in SCOPE.md.
+
+## 4. Potential (honest)
+
+| Horizon | Realistic outcome | Depends on |
+|---|---|---|
+| Near (HACS default + demo assets) | Low hundreds of ★; Telegram + forum traction | #9004 merge, GIF/video, EN forum/Reddit posts |
+| Medium (12 months of polish + registry depth) | Contender in the GUI-floorplan shortlist; maybe 0.5–1.5k★ if narrative sticks | Differentiation messaging vs easy-floorplan; onboarding magic |
+| Ceiling | Unlikely to dethrone ha-floorplan’s power-user base; unlikely Bubble-scale | Niche size + single maintainer |
+
+**Usefulness:** high for the target personas (admin builds once; household/kiosk
+use View). **Commercialization:** none intended (MIT, local-first) — success =
+installs and unpaid maintenance load.
+
+## 5. Strategic risks
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| easy-floorplan owns the “no YAML floorplan” mindshare | **High** | Sharpen README differentiation (server sync, areas, overlays); ship demo GIF now |
+| HA core ships a native spatial plan | **High (latent)** | Deepen floors/areas registry integration; speed of iteration |
+| HACS default #9004 stuck for months | **Medium** | Custom-repo path works; social proof before merge |
+| Single-maintainer bus factor | **Medium** | Docs + tests already strong; avoid feature sprawl |
+| Frontend API churn (`hass` internals) | **Medium** | Minimal surface; CI against current HA in harness |
+| Scope creep toward furniture CAD | **Self-inflicted** | SCOPE non-goals — do not chase easy-floorplan feature-for-feature |
+
+## 6. Positioning recommendation
+
+**One sentence:** *House Plan is the shared, area-aware live map of your Home
+Assistant home — not a drawing app for furniture.*
+
+Lead with: multi-device sync, bind room→area→devices appear, glow/climate/sun/
+vacuums, kiosk for wall tablets. Acknowledge: if you want to *draw walls and
+sofas from scratch*, use easy-floorplan; if you have a plan image and a real HA
+registry, use House Plan.
+
+## 7. Distribution checklist (status)
+
+| Lever | State (2026-08-05) |
+|---|---|
+| Public demo | **Live** — https://demo.houseplan.tech (`demo`/`demo`) |
+| Dev stand | https://dev.houseplan.tech |
+| Telegram | https://t.me/ha_houseplan |
+| HACS custom install | Works |
+| HACS default | **Queued** — hacs/default#9004 open since 2026-07-06 |
+| Demo GIF / video in README | Still a ROADMAP Phase 10 open item |
+| Forum Floorplan + Reddit posts | Drafts exist off-repo; posting still open |
+| Stars | **21** — traction problem, not a product-depth problem |
+
+## 8. What to refresh next
+
+When stars or competitor maturity move materially, update **this file first**,
+then sync the table in `PRODUCT.md`. Do not leave PRODUCT as the only market
+doc — it already went a month stale while easy-floorplan 40×’d.

docs/AUDIT-QUALITY.md

@@ -0,0 +1,132 @@
+# Audit — implementation quality
+
+> Snapshot: **2026-08-05**, product **v1.58.0**.
+> Severity: **critical / major / minor / nit**. No critical RCE found under
+> normal HA session auth.
+
+## 1. Architecture snapshot
+
+```
+src/                         Lit 3 Lovelace cards (houseplan + space-card)
+  houseplan-card.ts          ~8691 LOC — orchestration god-object
+  logic.ts / devices.ts / …  extracted pure modules (good)
+  styles.ts                  ~2223 LOC CSS-in-JS
+custom_components/houseplan/ HA integration (storage, WS, HTTP, trails)
+dist/ + frontend/            committed bundle (CI byte-compares)
+demo/                        Playwright harness + smoke_*.mjs
+tests_backend/               pure + HA-harness pytest
+```
+
+Bundle: **≈449 KB** raw / **≈128 KB** gzip — acceptable for a full editor+viewer.
+
+## 2. What is strong
+
+### Backend
+
+- Single write-auth helper (`auth.may_write`) with **fail-closed** when entry
+  missing (audit B2 lesson documented in the module).
+- Voluptuous validation with **cross-language option-list tests** that parse
+  `DISPLAY_MODES` / `TAP_ACTIONS` from `logic.ts` — rare and valuable.
+- Config CAS via `expected_rev`; plan COW + quotas; never-delete-on-inference
+  file policy (SCOPE).
+- Geometry migration with durable `geom_pending` intent (HP-1490 class).
+- Content HTTP: `requires_auth`, signed URLs for `<image href>`, SVG CSP sandbox.
+- Diagnostics / repairs / system_health present; `quality_scale.yaml` mostly
+  **honest** (`test-coverage`, `strict-typing`, docs todos marked todo).
+
+### Frontend (extracted brain)
+
+- Tap security model in `resolveTapAction` — locks/alarms never toggle from the
+  plan; cover garage/door/gate guarded; `run` limited to automation/script/scene.
+- Pure geometry / devices / sun / vacuum / resize / align-grid / signing modules
+  with solid `node:test` coverage (~270 tests).
+- Shared `config-store` + space-geometry/render for `houseplan-space-card`.
+- Optimistic UI without rollback is **documented intentional** (ARCHITECTURE).
+
+### Process
+
+- Four test layers + smoke policy (“`[manual]` must have a failing auto check”).
+- Dual CHANGELOG (en/ru), SCOPE guard rail, CONTRIBUTING five-minute loop.
+- CI: hacs + hassfest + frontend + backend + smoke job.
+
+## 3. Findings (ranked)
+
+| # | Sev | Finding | Where |
+|---|---|---|---|
+| 1 | **major** | God-object card: ~8691 LOC, ~359 methods, ~125 private fields; `render()` ~382 lines. Smokes-only coverage for orchestration. | `src/houseplan-card.ts` |
+| 2 | **major** | `strict: true` hollowed by `noImplicitAny: false`; ~200 `any` sites in the card alone; `hass: any` everywhere | `tsconfig.json`, card / devices / logic |
+| 3 | **major** | Write-policy split: UI `_canEdit` is always admin-gated; API default `admin_only=False` lets **any** authenticated user write via WS/HTTP | `houseplan-card.ts` ≈L247–249, `auth.py` |
+| 4 | **major** | `_canEdit` fails **open** when `hass.user` is missing (`is_admin !== false`) | card ≈L248 |
+| 5 | **major** | `styles.ts` ~2223 LOC — second maintainability sink; untested | `src/styles.ts` |
+| 6 | **minor** | `layout/update` has no `expected_rev` — multi-tablet last-writer-wins per point | `websocket_api.py` |
+| 7 | **minor** | Marker `binding` is bare `str`; `ripple_color` not hex-matched; decor `w`/`h` allow negatives via `_NORM` | `validation.py` |
+| 8 | **minor** | Card-level `tap_action` / `resolveTapAction` cardDefault is dead / ignored — confusing API surface | `types.ts`, click path |
+| 9 | **minor** | Store `_async_migrate_func` is a no-op; real migrations live ad-hoc in setup | `store.py`, `__init__.py` |
+| 10 | **nit** | `quality_scale.yaml` cites `test_config_flow.py`; file is `test_ha_config_flow.py` | quality_scale.yaml |
+| 11 | **nit** | Duplicated `fireEvent` / `navigate` in card + space-card | both files |
+| — | positive | Forbidden-domain tap model + confirm + cover guards | `logic.ts` |
+| — | positive | Signed content + SVG sandbox | `http_api.py`, `signing.ts` |
+
+**No critical** auth bypass of HA sessions found. Closest systemic issue is
+finding #3 (API openness vs UI) under the default options.
+
+## 4. TypeScript & tooling
+
+| Item | State |
+|---|---|
+| `tsc --noEmit` in build | Yes — correct (rollup TS plugin can warn-and-ship) |
+| ESLint / Prettier | **Absent** |
+| `noImplicitAny` | **Off** |
+| Frontend unit of the Lit class | **None** |
+| mypy strict (backend) | quality_scale **todo** |
+
+## 5. Test map
+
+| Layer | What it proves | Gap |
+|---|---|---|
+| `npm test` (~270) | Pure logic, i18n parity, tap security, geometry | Not the card shell |
+| `pytest` pure | validation.py without HA | — |
+| HA-harness (py≥3.13) | setup, WS races, auth, upload, geometry repair | Coverage % unmeasured |
+| `demo/smoke_*.mjs` (~100) | Real pointer/UI against fake hass | Pixel flakes (`smoke_opening_measure`); no Safari/Companion matrix |
+
+Human checklist in TESTING.md last full self-run recorded at **v1.21.1** while
+product is at **v1.58.0** — auto net grew; documented human pass did not.
+
+## 6. Docs drift (quality of truth)
+
+| Doc | Drift |
+|---|---|
+| `ARCHITECTURE.md` intro | Still mentions old `src/data/house.ts` / 1489×1053 era in places; square/infinite canvas sections newer |
+| `UX-MODES.md` header | Still says “No code has been changed yet” — Phase 11 shipped |
+| `PRODUCT.md` competitor table | **Stale** — easy-floorplan 11→430★ (see AUDIT-MARKET) |
+| `STATUS.md` | Generally current as of 2026-08-04 |
+
+Docs discipline is a project strength; these drifts are fixable and should be
+treated as debt, not ignored.
+
+## 7. Top 10 technical debt (actionable)
+
+1. Split `houseplan-card.ts` into shell + Plan/Devices/Decor editors + dialogs.
+2. Turn on `noImplicitAny` incrementally; type a thin `Hass` surface.
+3. Align write policy: wire UI to `admin_only`, or default `admin_only=True`.
+4. Fail closed on missing `hass.user`.
+5. Add CAS / expected_rev to `layout/update` (or document single-writer assumption).
+6. Split `styles.ts` by feature surface.
+7. Tighten MARKER_SCHEMA (`binding`, colors, decor extents, space ids).
+8. Unit-test orchestration hotspots (`_clickDevice`, write-chain conflicts, modes).
+9. Real Store migrations or document setup-time migrations as the only path.
+10. Remove or re-wire dead card-level `tap_action` / cardDefault.
+
+Detailed priority and sequencing: [`AUDIT-RECOMMENDATIONS.md`](AUDIT-RECOMMENDATIONS.md).
+
+## 8. Quality-scale honesty check
+
+| Claim | Audit view |
+|---|---|
+| Bronze structural items `done` | Accurate |
+| Silver unloading / owner `done` | Accurate |
+| Gold diagnostics / repairs `done` | Accurate |
+| `test-coverage` / `strict-typing` / docs examples `todo` | Accurate — keep them todo until measured |
+| `config-flow-test-coverage` path typo | Nit — fix filename in yaml |
+
+Overall: self-assessment is trustworthy; do not mark coverage done without a number.

docs/AUDIT-RECOMMENDATIONS.md

@@ -0,0 +1,99 @@
+# Audit — prioritized recommendations
+
+> Snapshot: **2026-08-05**. Priorities for humans and agents.
+> P0 = do soon (risk or traction). P1 = next engineering cycle.
+> P2 = important but schedulable. P3 = niceties / when touching adjacent code.
+>
+> Status column: update in-place when an item ships (`done YYYY-MM-DD` or
+> `dropped — reason`).
+
+## P0 — traction & trust (this month)
+
+| ID | Action | Why | Status |
+|---|---|---|---|
+| P0-1 | Ship **demo GIF/video** on README (real product motion: glow + tap light + kiosk) | Biggest adoption lever; ROADMAP Phase 10; easy-floorplan is winning attention without our counter-demo | open |
+| P0-2 | Publish EN **forum Floorplan + Reddit** posts (drafts exist off-repo) | Social proof before/while HACS #9004 waits | open |
+| P0-3 | Refresh **README differentiation** vs easy-floorplan (server sync, areas→devices, overlays — not furniture CAD) | PRODUCT table is a month stale; narrative gap is urgent | open |
+| P0-4 | Align **write policy**: either default `admin_only=True` **or** drive `_canEdit` from the same option; fail closed if `hass.user` missing | UI↔API inconsistency; household persona assumption | open |
+| P0-5 | Keep watching **hacs/default#9004** — no code action; do not spam maintainers | Queue is months-scale; custom-repo remains the path | open |
+
+## P1 — maintainability (next engineering focus)
+
+| ID | Action | Why | Status |
+|---|---|---|---|
+| P1-1 | **Extract** from `houseplan-card.ts`: Plan editor, Devices editor, Decor/backdrop tools, dialogs → separate modules/components; keep pure math where it is | 8691 LOC god-object is the #1 engineering risk | open |
+| P1-2 | Enable **`noImplicitAny`** in stages (devices → logic → card shell); introduce a thin typed `Hass` facade | `strict` is currently nominal | open |
+| P1-3 | Split **`styles.ts`** by surface (view / editors / dialogs / kiosk) | 2223 LOC CSS sink | open |
+| P1-4 | Unit-test **orchestration hotspots**: `_clickDevice` policy wiring, config write-chain conflict, mode enter/exit | Smokes-only today | open |
+| P1-5 | Add **`expected_rev` (or per-key CAS)** to `layout/update` *or* document “single active editor” as the contract in ARCHITECTURE | Multi-tablet drag races | open |
+
+## P2 — product depth inside SCOPE
+
+| ID | Action | Why | Status |
+|---|---|---|---|
+| P2-1 | **Registry-driven room suggestions** after floors-import (bind suggested polygons/areas) | SCOPE J4; PRODUCT “next move”; moat vs card-only peers | open |
+| P2-2 | Plan-level **security glance** badge (all locked / N open) | SCOPE known gap; kiosk value | open |
+| P2-3 | Touch ergonomics pass on Plan/Devices editors | Admin-on-tablet persona | open |
+| P2-4 | Options-flow richness: expose exclude domains / LQI thresholds / clearer `admin_only` | ROADMAP Phase 8 | open |
+| P2-5 | Plan upload **auto-downscale** / max-dimension guidance | ROADMAP Phase 9; prevents huge SVG pain | open |
+| P2-6 | Replace remaining **real-house README screenshots** with synthetic | STATUS privacy watchlist | open |
+
+## P3 — quality-scale & hygiene
+
+| ID | Action | Why | Status |
+|---|---|---|---|
+| P3-1 | Measure backend coverage; drive toward **≥95%** or revise the goal honestly | quality_scale todo | open |
+| P3-2 | **mypy strict** (or staged) | Platinum todo | open |
+| P3-3 | `docs-troubleshooting` + `docs-examples` (Gold) | quality_scale todo | open |
+| P3-4 | Tighten MARKER_SCHEMA (`binding` pattern, hex `ripple_color`, positive decor sizes, space id regex) | Validation gaps | open |
+| P3-5 | Fix quality_scale filename (`test_ha_config_flow.py`); remove or re-wire dead card `tap_action` | Nits that confuse agents | open |
+| P3-6 | Refresh stale doc headers: ARCHITECTURE tree, UX-MODES “no code yet”, PRODUCT competitor table | Truth decay | open |
+| P3-7 | Investigate / soften `smoke_opening_measure` magnet `1e-6` placement checks | Known env-sensitive red | open |
+| P3-8 | Exception / icon translations | ROADMAP Phase 8 | open |
+| P3-9 | Resource cleanup on integration removal + YAML-mode fallback doc | ROADMAP Phase 8 | open |
+
+## Explicit do-not-do (reaffirmed)
+
+Do **not** prioritize these even if competitors ship them:
+
+1. Furniture / wall CAD (easy-floorplan’s game).
+2. 3D / glb viewers.
+3. Vacuum clean/zone **commands** (display-only stays).
+4. Cloud sync / accounts.
+5. Music-note / directional TV ripple polish from issue #3 backlog.
+6. History rewrite to purge old house assets from git (breaks HACS tags).
+
+## Suggested sequencing for an agent sprint
+
+```
+Week theme A — Trust & story
+  P0-3 README diff → P0-1 demo video → P0-2 forum/Reddit
+  P0-4 write-policy alignment (small code + options default)
+
+Week theme B — Carve the god-object
+  P1-1 extract one editor (Devices is smallest) + P1-4 tests for the seam
+  P1-2 noImplicitAny on the extracted module only
+
+Week theme C — Moat feature
+  P2-1 registry room suggestions (design in ARCHITECTURE first)
+```
+
+Avoid mixing A+B+C in one PR. Distribution P0s do not require waiting on P1.
+
+## Success metrics (lightweight)
+
+| Metric | Now (2026-08-05) | Near-term target |
+|---|---|---|
+| GitHub ★ | 21 | 100+ after GIF + posts + HACS visibility |
+| HACS default | #9004 open | merged (external) |
+| `houseplan-card.ts` LOC | ~8691 | <5000 after first extract wave |
+| Backend coverage | unmeasured | number published in quality_scale comment |
+| Open P0 items | 5 | 0 |
+
+## Pointers
+
+- Market context: [`AUDIT-MARKET.md`](AUDIT-MARKET.md)
+- Quality detail: [`AUDIT-QUALITY.md`](AUDIT-QUALITY.md)
+- Gaps / matrix: [`AUDIT-FUNCTIONAL.md`](AUDIT-FUNCTIONAL.md)
+- Guard rail: [`SCOPE.md`](SCOPE.md)
+- Living ops: [`STATUS.md`](STATUS.md)

docs/AUDIT.md

@@ -0,0 +1,75 @@
+# Project audit — index
+
+> **Audience:** future humans and agents. Read this before proposing features,
+> refactors, or go-to-market work. Snapshot date: **2026-08-05**. Product
+> version audited: **v1.58.0**.
+>
+> **Policy:** this pack supplements (does not replace) `PRODUCT.md`,
+> `STATUS.md`, `SCOPE.md`, `ARCHITECTURE.md`, `ROADMAP.md`. When they disagree
+> on *current* market numbers, prefer this pack until `PRODUCT.md` is refreshed.
+
+## Pack contents
+
+| File | What it answers |
+|---|---|
+| [`AUDIT-MARKET.md`](AUDIT-MARKET.md) | Potential, demand shape, competitors, positioning, risks |
+| [`AUDIT-QUALITY.md`](AUDIT-QUALITY.md) | Implementation quality, architecture, security, tests, tech debt |
+| [`AUDIT-FUNCTIONAL.md`](AUDIT-FUNCTIONAL.md) | Feature integrity, systematicity, claim↔code parity, gaps |
+| [`AUDIT-RECOMMENDATIONS.md`](AUDIT-RECOMMENDATIONS.md) | Prioritized actions (P0–P3) with rationale |
+
+## Executive verdict (one screen)
+
+**House Plan is a high-craft, scope-disciplined product in a niche that suddenly
+got a fast-growing peer.** Engineering quality (validation, tap security, CI
+layers, quality-scale honesty, docs discipline) is well above typical HACS
+cards. The dominant risks are no longer “can we build it?” — they are
+**discoverability**, **maintainability of a 8.7k-LOC Lit god-object**, and
+**losing the GUI-floorplan narrative to easy-floorplan** (≈430★ vs our ≈21★
+as of 2026-08-05; a month earlier PRODUCT.md listed easy-floorplan at 11★).
+
+| Dimension | Grade | One-line |
+|---|---|---|
+| Product mission / scope discipline | **A** | SCOPE.md is unusually sharp; non-goals held |
+| Feature depth vs mission | **A−** | Jobs J1–J7 closed; a few polish gaps |
+| Implementation quality (backend) | **A−** | Strong WS/HTTP/auth/file races; coverage % still todo |
+| Implementation quality (frontend) | **B** | Pure modules good; card shell is a maintainability bomb |
+| Test strategy | **A−** | 4 layers + smoke policy; human matrix stale |
+| Competitive moat (technical) | **A−** | Server-side storage + area-bound rooms still unique |
+| Competitive position (market) | **C+** | Traction lagging the wave; HACS default still queued |
+| Distribution / social proof | **C** | Demo stand exists; forum/Reddit/GIF still open |
+| Bus factor / docs | **B+** | Excellent docs; single maintainer |
+
+**Do not** expand into 3D, furniture CAD, vacuum commands, or cloud — SCOPE
+forbids them and competitors already own parts of that surface. **Do** close
+the distribution gap and keep the moat (registry depth, multi-client storage,
+overlays that feel like a home — not a drawing app).
+
+## How agents should use this
+
+1. Before a feature: check `SCOPE.md` → then `AUDIT-FUNCTIONAL.md` gaps → then
+   `AUDIT-RECOMMENDATIONS.md` priority.
+2. Before a refactor: read `AUDIT-QUALITY.md` top-10 debt; prefer extracting
+   from `houseplan-card.ts`, not rewriting working pure modules.
+3. Before go-to-market or README claims: read `AUDIT-MARKET.md` — star counts
+   and competitor maturity change monthly; re-verify with GitHub API.
+4. After acting on a P0/P1 item: update the relevant AUDIT file’s “Status”
+   line in the same commit (short note + date), and bump STATUS.md watchlist
+   if the project-level state changed.
+
+## Method
+
+- Read: PRODUCT, STATUS, ARCHITECTURE, ROADMAP, SCOPE, UX-MODES, TESTING,
+  CONTRIBUTING, quality_scale.yaml, manifest, key `src/` + `custom_components/`
+  modules.
+- Metrics: `wc -l`, bundle size, `npm`/`pytest` inventory, GitHub API star
+  counts (2026-08-05), hacs/default#9004 state.
+- Code-quality pass: god-object sizing, auth UI↔API, tap-action model,
+  validation parity, test layer map.
+- Explicitly **not** a full security penetration test or coverage measurement.
+
+## Related living docs
+
+- Market rationale (older): `PRODUCT.md` — refresh after this audit lands.
+- Guard rail: `SCOPE.md`
+- Current ops snapshot: `STATUS.md`
+- Design: `ARCHITECTURE.md`, `CANVAS.md`, `BACKDROP.md`, `VACUUM.md`, `SUN.md`

docs/PRODUCT.md

@@ -3,6 +3,15 @@
 *Written 2026-07-05. Sources: GitHub API star counts and HA docs verified 2026-07-06;
 see links inline. Update this file when the landscape shifts.*
 
+> **2026-08-05 refresh.** A full audit pack now lives under
+> [`docs/AUDIT.md`](AUDIT.md) (market / quality / functional / recommendations).
+> **Critical market change:** [easy-floorplan](https://github.com/nicosandller/easy-floorplan)
+> grew from **11★ → ≈430★** in ~one month and is a real GUI peer — the July claim
+> that the niche is “currently unoccupied” is **obsolete**. Our technical moat
+> (server-side integration, area-bound rooms, overlays, quality-scale) still
+> holds; traction and messaging do not. Prefer [`AUDIT-MARKET.md`](AUDIT-MARKET.md)
+> for current competitor numbers until this file is rewritten.
+
 ## What the product is
 
 An interactive floor plan for Home Assistant delivered as one HACS package:
@@ -23,7 +32,7 @@ live robot vacuums, en/ru localization). GUI-first: no YAML, no hand-made SVG.
 | [zigbee-floorplan-card](https://github.com/TheLarsinator/zigbee-floorplan-card) | 71 | LQI over a plan image | single-purpose; validates our LQI feature |
 | [kishorviswanathan/ha-floorplan](https://github.com/kishorviswanathan/ha-floorplan) (2026-01) | 155 | external web editor → YAML export | editor outside HA, still YAML at runtime |
 | [Padraigggs-ha-interactive-floorplan](https://github.com/Padraiggg/Padraigggs-ha-interactive-floorplan) (2026-03) | 41 | editor+viewer cards, "no YAML" | weeks old, card-only, no server-side integration |
-| [easy-floorplan](https://github.com/nicosandller/easy-floorplan) (2026-05) | 11 | draw walls/furniture in the card | drawing-centric, immature |
+| [easy-floorplan](https://github.com/nicosandller/easy-floorplan) (2026-05) | 11→**≈430 by 2026-08-05** | draw walls/furniture in the card | drawing-centric (still our non-goal) but **no longer immature** — fastest GUI peer; see AUDIT-MARKET |
 
 **Demand evidence:** a dedicated [Floorplan forum category](https://community.home-assistant.io/c/third-party/floorplan/28);
 the "100% Floorplan UI" mega-thread (500k+ views); a visible 2025–2026 wave of new
@@ -42,14 +51,17 @@ hundreds of stars in the first year *if* discoverability is solved (HACS default
 demo GIF + forum post). Bubble Card (4.4k★) proves polished GUI cards can go
 quasi-mainstream; ha-floorplan's 1.5k★ with a hostile workflow shows the demand floor.
 
-**Unique position — currently unoccupied.** Nobody else combines: server-side config
-(integration + `.storage`, survives dashboard edits, shared across users/devices,
-optimistic locking, live multi-client sync) + in-card room polygon editor bound to HA
-areas + curated auto-placement + drag layout + LQI/temperature overlays + config flow +
-en/ru localization + CI/quality-scale discipline. The newcomers are card-only toys so
-far; the incumbent is powerful but YAML/SVG-locked. Our moat grows if we integrate
-deeper with the areas/floors registry (Phase 9) — that is the direction HA core itself
-is signalling with the native Areas dashboard.
+**Unique technical position — still real; market exclusivity — gone.** Nobody else
+combines: server-side config (integration + `.storage`, survives dashboard edits,
+shared across users/devices, optimistic locking, live multi-client sync) + in-card
+room polygon editor bound to HA areas + curated auto-placement + drag layout +
+LQI/temperature/glow/sun/vacuum overlays + config flow + en/ru localization +
+CI/quality-scale discipline. The incumbent (ha-floorplan) is still YAML/SVG-locked.
+But **easy-floorplan** (2026-08) is a shipping GUI card with an order of magnitude
+more stars than us — card-only / furniture-drawing, yet owning the “no YAML” mindshare.
+Our moat grows if we integrate deeper with the areas/floors registry (Phase 9) and
+*tell that story* in the README/demo — that is the direction HA core itself is
+signalling with the native Areas dashboard.
 
 **Risks.**
 1. *HA core ships a native spatial plan.* The Areas dashboard is grid-based today, but

docs/STATUS.md

@@ -148,6 +148,11 @@
 
 ## Open items / watchlist
 
+0. **Full project audit (2026-08-05)** — pack at [`docs/AUDIT.md`](AUDIT.md)
+   (market, quality, functional integrity, prioritized recommendations). Key
+   takeaway: engineering depth is strong; **easy-floorplan ≈430★** is now the
+   traction threat; P0s are demo GIF + forum posts + write-policy UI↔API align.
+   Agents: read the pack before proposing features or refactors.
 1. **hacs/default PR #9004** — accepted by the bot into the review queue ('New default
    repository' label). Minor issues ⇒ the bot drafts the PR (fix and re-ready).
 2. GitHub auth: fine-grained PAT (Contents R/W, issued 2026-07-23) in the sandbox