# Settings Home & Phone Completion Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Finish the Home & Phone Settings page on Panama's shared Settings vocabulary and give the global reset path a named, durable Home preference API.

**Architecture:** `HomePhonePage` adopts `SettingsPage` for the shared scrolling/title/lede scaffold while retaining its specialized catalog, reorder, alias, and phone controls. `HomePreferences.resetHomeDefaults()` becomes the sole Home-store reset boundary: it returns the store to fresh-install state and writes immediately so `SystemSettings.restoreDefaults()` can call it without mutating aliases.

**Tech Stack:** Quickshell 0.3 QML, QtQuick, Bash contract tests, Hyprland.

**Spec:** `docs/superpowers/specs/2026-08-17-panama-cohesion-design.md`

## Global Constraints

- Do not touch `SystemSettings.qml`, `PreferenceSchema.qml`, keybinds, or Claude's shared row implementations in this branch.
- Preserve ordered Home favorites, aliases, first-four Control Center badges, search, drag and keyboard reorder, retry state, Home Assistant status copy, and BlueBubbles availability behavior.
- Automated tests must not toggle or dim a real light and must not launch BlueBubbles.
- New behavior follows red-green TDD; fixture and state directories remain isolated from the live desktop.
- No mock phase and no new visual direction: this is cohesion work against the already-approved design.

---

### Task 1: Shared Home & Phone page and named reset boundary

**Files:**
- Modify: `config/dot/quickshell/config/HomePreferences.qml`
- Modify: `config/dot/quickshell/home-preferences-harness.qml`
- Modify: `config/dot/quickshell/modules/settings/HomePhonePage.qml`
- Modify only if required for shared vocabulary compatibility: `config/dot/quickshell/modules/settings/HomeFavoriteCard.qml`
- Modify only if required for shared vocabulary compatibility: `config/dot/quickshell/modules/settings/AvailableLightRow.qml`
- Modify: `tests/quickshell/home-preferences-contract`
- Modify: `tests/quickshell/home-phone-settings-contract`

**Interfaces:**
- Consumes: `SettingsPage { title; lede; default content }`, existing `SettingsCard`, `SettingRow`, `ActionRow`, `TextRow`, `HomeAssistant`, `SystemSettings.bluebubblesAvailable`, and writable `HomePreferences` adapter state.
- Produces: `HomePreferences.resetHomeDefaults(): void`, which sets `favorites` to `[]`, sets `initialized` to `false`, clears stale save error state, and invokes `preferencesFile.writeAdapter()` immediately after stopping the debounce timer.

- [ ] **Step 1: Write failing contracts**

Add `reset()` to the isolated `home-pref-test` IPC harness. Extend `home-preferences-contract` to seed aliases/order, invoke reset, and require both IPC state and `panama-home.json` to become exactly `{"initialized":false,"favorites":[]}` without waiting for the 180 ms debounce interval. Extend `home-phone-settings-contract` to require `SettingsPage {`, `title: "Home & Phone"`, and the existing lede through `lede:`, while rejecting the copied root `Flickable` scaffold.

- [ ] **Step 2: Run contracts to verify RED**

```bash
tests/quickshell/home-preferences-contract
tests/quickshell/home-phone-settings-contract
```

Expected: the preference contract fails because `reset` is missing; the page contract fails because the page still owns a copied `Flickable` scaffold.

- [ ] **Step 3: Implement the reset API and shared page scaffold**

Implement this public boundary in `HomePreferences.qml`:

```qml
function resetHomeDefaults(): void {
    persistTimer.stop();
    values.favorites = [];
    values.initialized = false;
    root.saveError = "";
    preferencesFile.writeAdapter();
}
```

Replace the `HomePhonePage` root `Item` plus nested `Flickable`/title/lede scaffold with:

```qml
SettingsPage {
    id: root
    objectName: "home-phone-page"
    title: "Home & Phone"
    lede: "Choose what appears in Control Center and keep phone continuity close at hand."
    // Existing SettingsCard content remains in order.
}
```

Use shared `ActionRow` or `TextRow` only where their single-action/read-only contracts preserve all current status and accessibility behavior. Keep specialized rows when the shared primitive would lose information.

- [ ] **Step 4: Run focused contracts to GREEN**

```bash
tests/quickshell/home-preferences-contract
tests/quickshell/home-phone-settings-contract
tests/quickshell/settings-pages-contract
tests/quickshell/settings-rows-contract.sh
tests/quickshell/settings-commit-reset-contract
```

Expected: every command exits 0; no test launches BlueBubbles or changes a real Home Assistant entity.

- [ ] **Step 5: Commit**

```bash
git add config/dot/quickshell/config/HomePreferences.qml \
  config/dot/quickshell/home-preferences-harness.qml \
  config/dot/quickshell/modules/settings/HomePhonePage.qml \
  config/dot/quickshell/modules/settings/HomeFavoriteCard.qml \
  config/dot/quickshell/modules/settings/AvailableLightRow.qml \
  tests/quickshell/home-preferences-contract \
  tests/quickshell/home-phone-settings-contract \
  docs/superpowers/plans/2026-08-18-settings-home-phone-completion.md
git commit -m "Finish Home and Phone settings cohesion"
```