# Home category redesign — Overview | My Home | Phone

Approved 2026-08-23 (mock B, "Rooms & Tabs"). Home absorbs Home & Phone and becomes a
three-tab category. Phase-2 feature picks: rooms grouping, phone vitals, Today card.
The reclaim-space prompt is removed. Deferred with reserved slots: Assist command box,
phone notification inbox, scenes/climate/cameras, now-playing, HA todos.

## Taxonomy

`SettingsRoutes` home category gains tabs; the `home-phone` category is deleted:

```
{ page: "home", label: "Home", tabs: [
    { page: "home",    label: "Overview" },
    { page: "my-home", label: "My Home" },
    { page: "phone",   label: "Phone" }
] }
```

`home` doubles as category id and first tab (the applications/users/privacy pattern).
New leaf ids `my-home`, `phone`. A new alias map in `SettingsRoutes.resolve()` sends
the retired `home-phone` id to `my-home` so muscle memory, old Vicinae commands, and
`panama-action settings-page home-phone` keep landing correctly. In-repo callers are
updated to the new ids anyway: `HomeControls.qml`, `panama-doctor`'s HA-warning target,
`Health.qml`'s `settingsTargets`.

## Pages

**HomePage.qml (Overview) — rebuilt.** Greeting header and weather lede stay. Then:
- A five-tile quick-action grid (new `HomeQuickTile.qml`): Focus session (start/end),
  Do Not Disturb (live toggle state), Health (→ `services`), Snapshots (→ `snapshots`),
  Storage (→ `storage`). Fixed set, per the phase decision.
- "This machine": the existing findings array unchanged (firewall exposure, security
  advisories, reboot-needed, health attention) plus the "Install N updates" row folded
  in as a finding when `Updates.total > 0`. The reclaim-space row is gone entirely.
- Two glance cards linking into the sibling tabs: My Home ("2 lights on · Living Room,
  Kitchen") and Phone ("iPhone · 82% · nearby"), each `openSettings("my-home"/"phone")`.
- "Today": `CalendarAgenda.nextEvent` with Join/Open; hidden when nothing upcoming or
  no calendar. Zero new plumbing — the service already streams.
- "Weather": the existing card, unchanged.
- The old Focus card and "Right now" containers card are retired (tiles and the System
  category cover them).

**MyHomePage.qml (new, `objectName: "my-home-page"`).** Absorbs the Home-Assistant half
of HomePhonePage:
- "Rooms" card: every catalog light grouped by HA area, rendered as interactive tiles
  (new `HomeLightTile.qml`: power square, name, state, brightness track for dimmables,
  "Control Center" pill on the first four favorites). Toggle → `HomeAssistant.toggleEntity`,
  brightness → `setBrightness` (commit-on-release, like `HomeBrightnessSlider`). Falls
  back to a single flat "Lights" section when areas are unavailable.
- "Accessories" card: the existing favorites editor (`HomeFavoriteCard` grid — alias,
  reorder, remove, Control Center badge) and the existing Available-lights search
  (`AvailableLightRow`), moved intact.
- "Home Assistant" card: the existing connection card (URL, token, save/clear, refresh,
  open) moved intact.
- Exposes `pageDiagnostics` (same shape as HomePhonePage's plus `rooms` summary);
  the IPC key in `settings status` renames `homePhone` → `myHome`.

**PhonePage.qml (new, `objectName: "phone-page"`).**
- Vitals strip: three stat blocks — Battery (% + charging), Signal (type + strength),
  Reachability — from the extended KdeConnect service. A stat whose datum is absent
  (unpaired, plugin missing) shows an em-dash, never an error.
- "Reach it" card: Ring, Send clipboard, Send file (FileDialog, the quicksettings
  pattern) via existing service functions; transfer progress/cancel as in Control Center.
- "Messages" card: BlueBubbles status + open (moved from HomePhonePage).
- "Device" card: pairing/plugins handoff to `connectivity` (as Control Center does).

`HomePhonePage.qml` is deleted. `HomeFavoriteCard`/`AvailableLightRow` survive under
MyHomePage.

## Service contracts (pages are written against these; helpers implement them)

**`panama-home-assistant areas` (new command).** REST-only: `POST /api/template`
rendering a Jinja template that emits `[{ "id", "name", "entities": [...] }]` via
`areas()` / `area_name()` / `area_entities()` / `tojson`. Same redacted error codes as
the other commands. `HomeAssistant.qml` gains `areas: []` (fetched with refresh) and
`rooms: [{ id, name, lights: [entity] }]` — catalog lights joined to areas, un-areaed
lights in a trailing "Other" bucket; empty `areas` ⇒ `rooms` is one unnamed bucket.

**`panama-kdeconnect status` (extended).** Per reachable paired device, read via
`busctl get-property` from the plugin objects (paths exist only when paired+reachable —
absence is data, not an error): `battery: { charge: int, charging: bool } | null` from
`org.kde.kdeconnect.device.battery`, `signal: { networkType: string, strength: 0-4 } | null`
from `...device.connectivity_report`. `KdeConnect.qml` surfaces `phoneBattery`,
`phoneSignal` (null when absent). Unit tests extend the two bridge test files' fake
busctl/CLI fixtures.

## Blast radius owned by this change

- `SettingsShell.qml`: `my-home`/`phone` cases + components; `homePhoneDiagnostics`
  plumbing renamed and repointed at MyHomePage (`SettingsWindow.qml`, `shell.qml`
  status JSON key `myHome`).
- `SettingsSearch.qml`: `home-phone` extraEntries re-pointed (`my-home` for Home
  Assistant entries, `phone` for phone entries); new entries for rooms, phone battery,
  ring, clipboard, Today.
- Generators re-run: Vicinae commands (`settings-home-phone` → `settings-my-home` +
  `settings-phone`; `home` still skipped so Overview adds no command), `docs/settings.md`.
- Contracts: `home-phone-settings-contract` rewritten as `my-home-settings-contract`
  (+ phone coverage), `control-center-contract` (Manage target), `health-ui-contract` /
  `panama-doctor-contract` (settings target), nav/jump/search/gnome-handoff/
  panama-commands re-verified against the new route table. `home-preferences-contract`
  and `phone-messages-contract` unchanged.
- Docs: settings README, manual chapter 05 (Home description), Welcome comment
  (fourteen categories).

## Non-goals (reserved slots, later phases)

Assist box, notification mirror/reply, scenes, climate, cameras, now-playing, todos,
HA WebSocket `--watch` streaming, customizable quick actions.