# Settings redesign — deferred test runs

No contract is executed while the settings redesign is in flight: many are live
harnesses that open windows, drive overlays, and run display transactions on
the real desktop. Everything below runs **once, at the end of the redesign,
with Gabriel's go-ahead**, and failures get fixed then.

## The run

- `panama test` — the full suite (**169** contracts as of the phase 6 Sound
  wave; the top-level README's count line is set to match and is itself
  checked by `setup/readme-contract`).

## Known items to verify or investigate at the end

- `quickshell/welcome-contract` — failed once ("the welcome screen did not
  open") during a full-suite run storming the live session; passed in
  isolation minutes earlier after the Welcome.qml comment edit. Suspected
  contention flake, not a regression. Confirm.
- `setup/readme-contract` — counts contracts; keep the README number in sync
  as later phases add contracts (phase 2 added `phone-page-contract`).
- Phase 2 additions already written and passing when last run:
  `my-home-settings-contract` (renamed from `home-phone-settings-contract`),
  `phone-page-contract`, extended `home_assistant_bridge_test.py` and
  `kdeconnect_bridge_test.py`.
- Each later phase (Appearance, …) appends its new/changed contracts here
  instead of running them.

## Phase 3 (Appearance) — append below

The contracts wave is done. Everything below is written and **still to be
RUN**. Nothing in this list has been executed against a live harness: the
static halves were checked against the tree, but every harness run and the
full-suite pass are deferred to the end-of-redesign sweep.

### New contracts (3)

| Contract | What it pins |
|---|---|
| `quickshell/theme-catalog-contract` | `config/themes.json` shape (10 themes, 6 dark / 4 light), every palette and ansi block accepted by the model's own validators, moon and day byte-identical to the shell's pre-theme literals, `ThemeCatalog.qml`'s embedded fallback carrying both, and `Theme.qml` holding no palette ternary. |
| `quickshell/video-wallpaper-contract` | Three independent pause reasons (`FocusModes.gameRunning`, `Battery.acOnline` plus the preference, `manuallyPaused`) and pausing over mpv's JSON IPC; the mpvpaper argv (`hwdec=vaapi`, `no-audio`, `loop-file=inf`, `input-ipc-server=`); the hyprpaper stop/start choreography and `Wallpaper.refreshActive()`; `Wallpaper.qml`'s video routing branches; the helper's 60-file cap, depth-2 scan and mp4/mkv/webm filter; the still frame for the lock screen; `WallpaperIndicator` in `Bar.qml`'s right-hand row with its `visible` binding, spoken name and no animation; the two schema keys; the doctor check id. |
| `quickshell/settings-titlebar-contract` | No minimize or maximize anywhere in the settings chrome (comments may say the words, code may not); `height: shown ? 48 : 0` so hiding collapses rather than leaving a hole; `buttonsLeft` side-awareness with exactly one anchor released per element; the close button's `activeFocusOnTab`, `Accessible.role`/`name`, Return/Space handlers and focus treatment, and that it is the only button; Escape declared on the shell rather than inside the bar; the `panamaTitlebar` schema entry and its Appearance row. |

### Updated contracts (6)

| Contract | What it now pins |
|---|---|
| `quickshell/accent-controls-contract` | Rewritten around the new editor: the nine surviving components and their qmldir lines, `AccentPicker`/`ThemeProfilePicker` staying deleted *and* unregistered, the four wells and their single `apply()` path, one hyprpicker invocation aimed by a remembered target, `ColorWell`'s hex validation committing on Enter and focus-out but never per keystroke, the six HSV labels, the debounce (the write lives in `commitTimer`, `changeChannel` writes nothing, `releaseTimer` hands the sliders back), `commitActive` recomputing `accentName` through `nearestCuratedName` with `selectProfile`/`updateActive` both routing into it, `Theme.qml` reading `ThemeProfiles.activePalette`, the Themes and Theme editor tabs, four search labels, and the no-animation ban extended over all nine components. Live half rewritten against the rebuilt harness. |
| `quickshell/theme-profiles-contract` | Node half rebuilt for the optional-field model: `shippedProfiles()` with no argument still returns the three built-in fallbacks (back-compat), the ten catalog records survive with palettes and ansi and no effects, palette/ansi/effects survive a stored record with per-key effect clamping, an invalid palette drops the FIELD not the profile, the caller's shipped list owns the id and name space, `editProfile` passes untouched fields through and a shipped fork carries the whole palette, `nearestCuratedName` mappings (mauve→orchid, gruvbox-yellow→amber, grey→slate, per scheme), and `derivePalette`/`resaturatePalette`/`deriveAnsi`/`mixHex` producing palettes the validators accept. Live half now pins the per-mode selection flow: a light/dark flip returns to the theme chosen on that side, never a forced default. |
| `quickshell/desktop-style-contract` | `titlebarMaximizeButton` and `titlebarDoubleClick` asserted **gone** from the schema and from `DesktopStyle`, along with `action-double-click-titlebar`; `panamaTitlebar` added (bool, def true, group titlebar); the button layout pinned close-only on both sides with `minimize`/`maximize` banned from the function body; the Appearance greps moved to Fonts/Sizes/Rendering with exactly five `FontPicker` rows and their five role labels, plus the honest-titlebar subtitle. |
| `quickshell/settings-ownership-contract` | The ColorScheme block was pinning `inactiveBorderDark`/`inactiveBorderLight`, which no longer exist. It now pins the inactive border as the active theme's `gutter`, bans a regrown literal, pins the accent border roles through the new `hyprColor(value, alpha)` signature, requires both roles to be restated on a theme change, and cross-checks Hyprland's startup literals against moon's and day's gutters in `themes.json`. |
| `quickshell/lock-screen-settings-contract` | The "between Background and Shell typography" ordering check named a card that no longer exists. It now pins Background → Video playback → Lock screen order, and that all three sit on the Background tab. |
| `quickshell/settings-search-contract` | Seven fixed cases added for the new surface: themes, theme editor, dark mode, Catppuccin, Gruvbox, video wallpaper, titlebar. The schema-label sweep already covers the new keys automatically. |

### Verified against the new tree, no edit needed

- `quickshell/settings-hardcoded-values-contract` — its scope is `Settings.qml`,
  which the theme work did not touch; `Theme.qml`'s literals are covered by
  `theme-catalog-contract` instead.
- `quickshell/wallpaper-service-contract` — already carries the video routing
  greps.
- `quickshell/wallpaper-settings-contract`, `wallpaper-policy-contract`,
  `settings-nav-contract`, `settings-pages-contract`, `manual-contract`,
  `settings-docs-contract`, `qmldir-registration-contract`,
  `settings-sync-contract`, `settings-backup-contract` — checked, nothing stale.
- `quickshell/panama-doctor-contract` — already lists `input.video-wallpaper`.

### Docs updated in the same wave

- `modules/settings/README.md` — new **Appearance** section (Themes, Theme
  editor, backgrounds still and moving, the honest titlebar); the border
  ownership paragraph corrected to the theme's gutter.
- `manual/05-making-it-yours.md` — rewritten Appearance chapter: the two
  galleries, per-mode memory, the four-well editor, video wallpapers, and why
  there is no minimize.
- Top-level `README.md` — contract count 162 → 165, confirmed by
  `setup/readme-contract`.

### Still open before the run

- The parallel pipeline wave's files (`gtk-theme-contract`,
  `lock-screen-theme-contract`, `palette-contract`, the two bridge tests) are
  not counted above. If that wave adds contracts, the README count line and the
  count in this file both need bumping again before the suite runs.
- `AppearancePage.qml`'s `tab` property defaults to `"background"` while its
  own comment says Themes leads. Decide which is intended before the run;
  nothing currently pins it either way.

## Phase 4 (Shell category) — append below

Spec: `2026-08-24-shell-category-redesign.md`. Desktop & Dock became **Shell**
(Bar · Dock · Control Center · Tiling · Workspaces), System gained **Sync &
Backup**, and the dock got its feature wave.

Unlike phases 2 and 3, the static and stubbed contracts in this wave **were
run** as they were written, and every one of them passed in isolation against
the tree. Two things are still deferred. The **live-harness halves** were not
run — the session was locked, and `dock-position-contract` opens a probe shell
while `settings-pages-contract` starts a settings harness, so those ran static-
only (`PANAMA_SETTINGS_STATIC_ONLY=1`) or not at all. And the **full-suite
pass**, the only thing that catches contention between harnesses, happens next
with Gabriel driving.

### New contracts (1)

| Contract | What it pins |
|---|---|
| `quickshell/bar-visibility-contract` | The bar's own neutral family: `barFg`/`barFgDim`/`barFgMuted` exist, each forced tone is anchored on one literal with both dims mixed off it, and the `theme` branch returns `root.fg`/`fgDim`/`fgMuted` **by identity** rather than a copied colour. All thirteen bar-text files bind to those tokens and none paints neutral text with the `fg` family (`Theme.alpha(Theme.fg, …)` hover and separator fills are allowed; semantic tones were never in scope). `Bar.qml`'s scrim reads `visible: Settings.barBackdrop`, its shadow reads `layer.enabled: Settings.barTextShadow` over exactly one `MultiEffect` layer, and neither may be a literal `true` — both shipped hardcoded during the build, which is the regression this exists for. Plus the four widget gates ANDed with their state conditions, `VitalsWidget`'s whole-pill `visible`, `exclusiveZone: Theme.barHeight` still literal, no animation anywhere in `Bar.qml`, and the two right-click jumps landing on `bar`. |

Mutation-checked while writing: hardcoding the shadow, returning a literal from
the `theme` branch, putting one widget back on `Theme.fg`, deleting the vitals
pill's own `visible`, and adding a `Behavior` to `Bar.qml` each fail it with a
message naming the actual problem.

### Updated contracts (5)

| Contract | What it now pins |
|---|---|
| `quickshell/dock-position-contract` | `DockPinsEditor` → `DockPinsStrip`: `preventStealing` moved to the strip, the retired ↑/↓ buttons replaced by the strip's own keyboard path (Left/Right move, Delete unpins), and a new section for the **live** dock's drag-to-reorder — commits once on release, and measures a slot from a real icon rather than a constant, because a `DockItem` is taller than it is wide and a constant is wrong on one orientation. |
| `quickshell/settings-jump-contract` | `DockContextMenu`'s "Dock settings" now opens `dock`, not the retired `desktop`. |
| `quickshell/settings-pages-contract` | Six new pages added to the page sweep (Bar, Dock, ControlCenter, Tiling, Workspaces, Sync); `vitalsIntervalMs` and the graphics ChoiceGrid now required on `BarPage` rather than `AppearancePage`, since the vitals are bar content and not surface appearance. |
| `setup/projects-contract` | The saved-projects list moved from the deleted `DesktopPage.qml` to `WorkspacesPage.qml`. |
| `quickshell/panama-commands-contract` | The launcher's new `dock-add-app` → `panama-action dock-pin` command. |

### Verified against the new tree, no edit needed

Every one of these was **run** and passed after the phase-4 changes landed:

- `quickshell/settings-search-contract` — the new `bar`/`controlCenter`/
  `datetime` groups and the re-pointed `dock`/`multitasking`/`edges`/`master`/
  `notices`/`focus` routes are covered by the schema-label sweep already.
- `quickshell/settings-ownership-contract` — the six intentional mirrors and the
  eleven README literals survived the rewrite; no new mirror was introduced.
- `quickshell/settings-nav-contract` — 14 categories, 38 leaves, 2 retired ids
  (`home-phone`, `desktop`).
- `quickshell/manual-contract`, `gnome-handoff-contract` (15 handoffs against
  38 pages), `control-center-contract`, `welcome-contract`,
  `accent-controls-contract`, `theme-catalog-contract`,
  `desktop-style-contract` — checked, nothing stale.

`welcome-contract` passed in isolation again here, which does not settle the
phase-3 flake above: that failure only appeared under a storming full-suite run.

### Docs updated in the same wave

- `docs/settings.md` and the 37 `settings-*` launcher commands — regenerated by
  `panama-settings-docs` and `panama-settings-commands`; both `--check` modes
  clean and both generators verified idempotent. `settings-desktop` is deleted,
  `settings-bar`/`-dock`/`-control-center`/`-tiling`/`-workspaces`/`-sync` are
  new, and `dock-add-app` joins them.
- `modules/settings/README.md` — new **Shell** section (the five tabs, the bar
  token design and why it exists, the pins strip and the live dock's gestures,
  the Control Center rule that only real sections get toggles) and a new
  **System › Sync & Backup** section. Appearance corrected from six tabs to
  five, saying where the Shell tab went.
- `manual/05-making-it-yours.md` — new **Shell** chapter section (bar
  legibility, widget switches, why `use24Hour` is not there, the pins strip,
  the dock's drag/right-click/scroll/preview gestures, **Add App to Dock**,
  Control Center sections) plus **Carrying settings between machines**.
  `manual/03-windows-and-workspaces.md` — the multi-display workspace switch
  now points at Displays, which is where it actually is, instead of the deleted
  Desktop & Dock page.
- Top-level `README.md` — contract count 165 → 166, recounted the way
  `panama test` collects (executable, or `*_test.py`, excluding fixtures and
  `__pycache__`).

### Still open before the run

- Four contracts in the working tree changed for reasons **outside** this
  phase and are not accounted for above: `declared-assets-contract` (`pkill`,
  from the video wallpaper work), `declared-dependencies-contract` (`cmp` →
  diffutils), `panama-doctor-contract` (29 → 30 check ids), and
  `lock-screen-helper-contract` / `video-wallpaper-contract` (theme-derived
  literals and the mpv IPC key quoting). Confirm each belongs to a wave that
  intended it before the suite runs.
- `tests/setup/update-command-contract` is untracked and belongs to the
  separate `panama update` design, not to this redesign. It **is** inside the
  166.
- `quickshell/dock-position-contract` has never had its **live** half run since
  the strip landed: it opens a probe shell, and this wave ran under a locked
  session. Its static half is what was verified. Run it first in the sweep.
- `quickshell/settings-pages-contract` passed static-only for the same reason.
  Its compositor-integration half — the settings harness, its IPC, and the
  page-open checks — is unverified against the six new pages.
- `Bar.qml` has one stray indentation glitch at its first `Row` (line 105).
  Cosmetic, untouched here because the file is not this wave's to reformat.
- 2026-08-24 full-suite run: 166 contracts, all green except `displays-contract`
  and `switcher-contract`, which are live interactive tests that cannot run
  behind hyprlock (both passed in the same day's unlocked run; neither
  subsystem changed in phase 4). Re-verify after unlock. **Still pending** —
  and `displays-contract` has since changed (phase 5), so this run is now the
  first one that exercises the new material as well.

## Phase 5 (Displays) — append below

Spec: `2026-08-24-displays-redesign.md`. The Displays page became canvas-first,
the per-monitor record grew VRR / colour profile / bit depth / SDR trim /
mirroring, and `pushLayout` stopped clobbering `monitors.lua`'s colour values.

**Nothing in this wave was run.** The test window was closed while it was
written: these are live harnesses that drive the real compositor through
display transactions, and three agents were editing the tree concurrently. What
*was* verified is listed as static below — evaluated directly against the
implementation files without a harness, by loading `monitors.lua` under a stub
`prefs` and by evaluating `DisplayLayout.js` in node. Everything else is
deferred to the sweep.

### Contracts changed (4)

| Contract | What it now pins | Verified |
|---|---|---|
| `quickshell/display-transaction-contract` | The extended record end to end: `applyRecord` merging one field at a time; `vrr` **omitted** when `vrrMode === -1` and emitted when it is not; neutral `sdrsaturation` omitted rather than written; a mirrored rule asking for `position = "auto"`; the mirror x/y carve-out in `matchesLayout`, and that it does not leak to an unmirrored record; a framebuffer format with no 8/10 mapping skipping the bit-depth assertion instead of blocking Keep; `confirm()` persisting the whole record; old-shape stored blobs still validating and an impossible `vrrMode` not; and seven refusals (self-mirror, primary mirroring, absent target, out-of-range vrr/profile/depth/SDR). | Bash and Python syntax; every new static grep checked against the landed `Displays.qml` (including the `vrrMode >= 0` omission branch in `monitorRule`) and against the extended harness; the fake compositor's rule parser dry-run on a real `monitorRule` payload, covering the `position = "auto"` and `mirror =` branches and the `mirrorOf: "none"` readback spelling. Every IPC assertion is **deferred**. |
| `quickshell/display-arrangement-contract` | **Flipped**: the canvas is no longer hidden below two displays. The `visible: … monitors.length` gate is now asserted *absent* from the `DisplayArrangement` element (by AST-free block scan, so the selector chips and Workspaces card may keep theirs), with a solo hint string, a `draggable` flag, and an `enabled:` binding on the `DragHandler`. Plus the mirror badge: `Mirrors ` in the component, `mirrorOf` read off the rects, and two new harness fixtures — solo renders one rect with `draggable == false`, mirrored stacks rect 1 on rect 0 and flags it. | **Statically verified** against the rebuilt `DisplayArrangement.qml`: every grep hits, the `DragHandler`'s `enabled:` is found by the brace-matching helper, and the flip check was mutation-tested both ways — it fails on the pre-redesign page (where the gate sat on the enclosing card, not on the canvas) and passes once the gate is gone. The two new harness fixtures are **deferred**. |
| `quickshell/display-layout-contract` | Mirror geometry in `DisplayLayout.js`: a valid mirror validates; the mirrored record keeps its stored coordinates through `normalize` (the primary's anchor does not apply to a position nothing reads back); it contributes nothing to `bounds`; `canvasRects` stacks its rect on its target's and carries `mirrorOf`/`mirrored`. Five refusals: self, absent target, mirroring primary, a two-hop chain, and a non-string. | **Statically verified** in node against the real `DisplayLayout.js` — every expected value in the two new `jq` filters came from that run, including the 3140/80 the mirrored record keeps. Harness plumbing deferred. |
| `quickshell/displays-contract` | The Lua consumer half: `color_profile` / `bitdepth_value` / `vrr_value` / `sdr_value` / `mirror_value` present, `cm`/`bitdepth`/`sdrbrightness`/`vrr`/`mirror` emitted under Hyprland's own key names, a mirrored entry's `position` forced to `auto`, neutral SDR saturation and `vrrMode = -1` written as absence rather than as a value, and an entry with every new field impossible surviving with its geometry while each bad field drops. Plus the extended-record greps on `Displays.qml`. | **Statically verified**: the whole `LUA` block was run against `config/dot/hypr/monitors.lua` with a stub `prefs` and passes. The `Displays.qml` greps were checked by hand and all hit. The live compositor half is deferred. |

### Cross-agent shapes these contracts now pin

Written from the spec's pinned API while agents A and B worked in parallel, and
re-checked against their files as those landed:

- `DisplayArrangement.canvasSnapshot()` exposes `draggable` alongside
  `rects`/`scale`, and passes `canvasRects`' `mirrorOf`/`mirrored` through — it
  returns `canvasData.rects`, not the solo-shrunk `tiles`, which is what the
  new fixtures assert against. Confirmed in the landed component.
- The solo hint is pinned as the prefix `One display connected` rather than the
  full sentence, so the em dash cannot break the grep.
- The mirror badge is pinned as `Mirrors ` in `DisplayArrangement.qml`.
- `soloFixture`/`mirrorFixture` mutate `fixtureService.monitors` and call
  `resetDraft()`, which is what the component's own `onMonitorsChanged` does.
  Whether that ordering settles before `canvasSnapshot()` reads back is the one
  thing only a run can answer.

### Still open before the run

- ~~`PreferenceSchema.qml`'s stale `displays` detail string~~ — resolved: the
  detail now names color, VRR override, and mirroring, and the matching grep in
  `displays-contract` was updated in the same commit.
- `displays-contract` also greps `DisplaysPage.qml` for `selectedOutput`,
  `scalesForMode(`, `primaryFirstMonitors.map(` and `enabled: Displays.canConfirm`.
  All four still hit, but the page was still the pre-redesign one when this was
  written — re-check them once the rebuilt page lands, particularly
  `primaryFirstMonitors.map(`, since the spec replaces the "Connected display"
  picker card with selector chips.
- No contract file was added or removed, so the README count line stays at
  **166** and `setup/readme-contract` needs nothing.
- Run order for the sweep: `display-layout-contract` first (pure geometry, no
  compositor), then `display-transaction-contract` (fake compositor on `PATH`),
  then `display-arrangement-contract`, and `displays-contract` last — it is the
  only one that drives the physical display, and it refuses to start from a
  scale that does not match what `monitors.lua` ships.

## Phase 6 (Sound) — append below

Spec: `2026-08-24-sound-redesign.md`. The Sound page became a complete PipeWire
surface: honest device list with badges and a ghost row, per-channel speaker
test, microphone test, per-app mic mute and per-app output routing, alert-sound
theme, over-amplification, and native device profiles in place of the GNOME
handoff.

**Nothing in this wave was run.** Three agents were editing the tree
concurrently and every harness here drives the live audio graph — the page
harness constructs the real Sound page against the session's own PipeWire, and
the services harness starts a shell. What *was* verified is listed as static
below: bash syntax on every contract, the JSON and pw-metadata fixtures parsed,
and each service's own parsing logic replayed in node or Python against the
landed source so the expected values in the assertions are the values the code
actually produces.

### New contracts (3)

| Contract | What it pins | Verified |
|---|---|---|
| `quickshell/sound-cards-contract` | `SoundCards`' parse of `pactl -f json list cards`: profiles keyed by name becoming an ordered list sorted by pactl priority (the fixture deliberately lists them out of order, so insertion order fails), a profile pactl marked unavailable kept and flagged rather than dropped, `device.description` as the card name, the port hint naming the connected port and reading exactly `No port connected` when none is, `set-card-profile` argv, an empty card or profile name starting no write, unparseable output and a failing read both degrading into `lastError` with an array still in `cards`, and recovery on the next refresh. Plus the static grep on the live `-f json` command, which the fixture seam means nothing else exercises. | **Statically verified**: `SoundCards.parse` and `portHintFor` replayed in Python against the fixture — profile order, availability flags, descriptions and both port hints match the assertions exactly. Every IPC call is **deferred**. |
| `quickshell/sound-routing-contract` | `SoundRouting`: every stream of a group moved, by `object.serial` and not by node id (both are plausible numbers in a log); a serial-less stream falling back to its node id; an empty group or unnamed sink running nothing; and `routeToDefault` releasing the pin through `pw-metadata -n default -d <node-id> target.object` **and** the legacy `target.node`, never through `move-sink-input` — moving a stream to the current default pins it there, which is the bug the button undoes. Plus the id asymmetry both ways, `busy`/`lastError` on refusal, recovery, and the spec-required comment above `routeToDefault`. | **Statically verified** against the landed service: the argv shapes, the serial fallback, the two metadata keys and the early returns all read directly off `SoundRouting.qml`. The runs are **deferred**. |
| `quickshell/sound-defaults-contract` | The one distinction the ghost row depends on: `default.configured.audio.sink` and not `default.audio.sink`. The fixture sets them to different values and writes the configured one first, so neither "last key wins" nor a machine whose configured device is present can make it pass by accident. Also: an unconfigured session reading as `""` rather than as the effective device, an empty store, a non-JSON value on an unrelated key not taking the read down with it, a failed read leaving nothing invented, recovery, the ghost record and its label (Bluetooth address, AirPlay hostname, USB product string, empty), and a static ban on reading `preferredDefaultAudioSink`, which is null in exactly the case the service exists for. | **Statically verified**: `SoundDefaults.parse` and `label` evaluated in node against all five fixtures — every expected string in the contract came from that run. The IPC half is **deferred**. |

### Updated contracts (4)

| Contract | What it now pins | Verified |
|---|---|---|
| `quickshell/sound-page-contract` | Rebuilt around the new page. Kept: the two `SoundDeviceList`s, the Dictation negatives and handoff, the balance and device-row pins, the Quick Settings sharing. Dropped: `openGnomePanel("sound")` and `label: "Device profiles"` — both now asserted **absent**, replaced by the native profile card (`title:`, `SoundCards.cards`, `setProfile(`, `refresh()`, `lastError`). Added: `captureApplications` filtered by `AudioInStream` and reaching `SoundCaptureRow` with a per-app mute, a tracked `PwObjectTracker` over capture nodes, the row hiding itself when nothing is listening; the ghost row asked of `SoundDefaults.absent(root.output)`, rendering after the `Repeater`, and non-interactive by a brace-scan proving every `TapHandler`/`HoverHandler` carries `!root.ghost`; the `device.api` badges; over-amplification gated at 1.5 on the page and on Quick Settings' **output** slider only, with the >100% region marked; the four `SoundRouting` calls in `ApplicationVolumeRow`. The no-shell-out ban is unchanged on the four core files and now extended over all eleven page components. | **The whole static half was run** against the landed tree and passes. The harness half is **deferred**. |
| `quickshell/application-volume-contract` | Grouping pins unchanged; new `clampVolume` case for the `max` parameter — `setVolume(group, 1.4, 1.5)` lands 1.4 and unmutes, 2.5 clamps to 1.5, **no** max clamps to 1 (the default must not quietly follow the preference), a negative clamps to 0, and a non-numeric value changes nothing and returns false. | **Statically verified**: the landed `AudioStreams.js` evaluated in node produced byte-identical output to the `jq` filter's expectations. The IPC run is **deferred**. |
| `quickshell/osd-helper-contract` | Over-amplification and the blip, both out of `settings.json`. Every run now gets its own `XDG_CONFIG_HOME`, because the helper would otherwise read Gabriel's real preferences and pass or fail on which switches he has on. Pins `-l 1.5` on volume up **and down** (wpctl clamps the result, so coming down from 130% would snap to 100% without it), `-l 1` on the microphone in the same run, `-l 1` for off / key absent / file absent / malformed JSON, the blip on up/down/toggle and not on brightness or microphone, silence with `volumeChangeBlip` false, and silence with no sound file — with the OSD still shown in every degraded case. | **Bash syntax only.** The helper is agent A's and had not landed when this was written; see the open item below. |

### Cross-agent shapes these contracts pin

Written from the spec's pinned API while agents A and B worked in parallel, then
re-checked against their files as those landed:

- `PANAMA_SOUND_CARDS_FIXTURE` and `PANAMA_SOUND_DEFAULTS_FIXTURE` are **file
  paths** the service `cat`s in place of the live command, read once at
  singleton construction. So a contract changes what the file *says* between
  cases rather than where it points, and deletes it to make a read fail.
  Confirmed against both landed services.
- `sound-services-harness.qml` is new and shared by all three service
  contracts. Whichever contract is running sets an inert fixture for the two
  services it is not testing, so nothing reaches the live daemon and every line
  in a command log belongs to the service under test.
- `SoundDeviceList` asks `SoundDefaults.absent(output)` rather than comparing
  configured names itself — the service owns both the comparison and the label.
  The contract followed B's refactor to that shape.
- The ghost label is A's `SoundDefaults.label()`, so it reads
  `Bluetooth device (AA:BB:CC:11:22:33)` **with** parentheses. `SoundDeviceList`
  briefly had its own `tidyName()` producing the same string without them; the
  harness and the assertion track the service's version.

### Docs updated in the same wave

- `services/SettingsSearch.qml` — the seven hand-written Sound entries from the
  spec (Balance, Speaker test, Microphone test, Alert sound, Applications using
  the microphone, Move an application's audio, Device profiles) on top of the
  four that were already there, and `groupPages` gained `"sound": "sound"` so
  the new schema group self-indexes.
- Top-level `README.md` — contract count 166 → 169, recounted with the same
  `find` `setup/readme-contract` uses; that contract was run and passes.

### Still open before the run

- **`osd-helper-contract` is written against a `panama-osd` that had not
  landed.** It assumes two things of agent A's helper: that the settings file
  is resolved as `${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json` (the
  `panama-idle` / `panama-lid` spelling, not `panama-palette`'s
  `PANAMA_SETTINGS` override), and that the blip's sound file can be overridden
  with `PANAMA_OSD_BLIP_SOUND` (matching the existing `PANAMA_OSD_*` seams in
  the same script), which is the only way to exercise the missing-file branch
  deterministically. If A spelled either differently, the env names in
  `run_helper` are the only lines that need changing. Reconcile before running.
- The contract also now asserts `-l` on the **down** step, which the
  pre-redesign helper did not pass. The reasoning is in the contract; if the
  landed helper only limits the up step, that is a real bug at 150% and not a
  contract to relax.
- `sound-page-contract`'s runtime half asserts `.captureApplications >= 0` and
  `.captureRowVisible == (.captureApplications > 0)` — true on a machine where
  nothing is recording, which is the ordinary case. Getting a positive capture
  count under test would mean holding the microphone open from the contract;
  the grouping itself is covered by `captureTypesValid` and by the static greps.
- No contract in this wave has had its harness started. Run order for the
  sweep: `sound-defaults-contract`, `sound-cards-contract`,
  `sound-routing-contract` (all three fixture-fed and cheap), then
  `application-volume-contract`, then `osd-helper-contract`, and
  `sound-page-contract` last — it is the only one that constructs the real page
  against the session's own audio graph.
- Nothing in this wave plays a sound on purpose, but `sound-page-contract`
  constructs `SoundPage`, whose microphone test and channel strip are one
  IPC-less click away from `pw-play`. The harness exposes no method that
  triggers either; keep it that way.

## Stabilization pass — 2026-08-24 — THE RUN HAPPENED

Three read-only reviewers swept the whole redesign (37 findings), three fix
waves applied them all, and the full suite then ran three times with Gabriel's
go-ahead: 162/169, 168/169, then **169/169 green**. The seven interim failures
were four suite-contention flakes (pass solo; theme-profiles hardened with a
catalog-settle wait) and three contract bugs (display-layout's stale mirror
expectation, osd-helper's non-atomic stub log + a set -u `local` expansion
trap, sound-cards' jq context rebind). displays-contract and switcher-contract
— the locked-session holdovers — both pass unlocked. Later phases append new
deferred contracts below as before; this line is the baseline they diverge
from.

## Phase 7 (Notifications & Focus) — append below

Spec: `2026-08-24-notifications-focus-redesign.md`. Notifications & Focus became
two tabs. Per-application rules grew from one bool to seven fields with a real
editor behind them, Do Not Disturb gained a second exception, and focus modes
got create/rename/delete/reorder plus trigger-kind editing on a page of their
own.

**Nothing in this wave was run.** Three agents were editing the tree
concurrently, and the one runtime harness here (`notification-app-rules-contract`)
boots a real Quickshell against a private D-Bus session. What *was* verified is
listed as static below: `bash -n` on every changed contract, and — for the two
contracts whose assertions are computed — the extracted blocks replayed in
`bun` and `python3` against the landed services, so the expected values in the
assertions are the values the shipped code actually produces.

### New contracts (0)

None. The redesign added surface to services and pages that already had
contracts, so the README count line stays at **169** and `setup/readme-contract`
needs nothing.

### Updated contracts (4)

| Contract | What it now pins | Verified |
|---|---|---|
| `quickshell/notification-app-rules-contract` | The rule shape, as two properties rather than a literal: every field past `enabled` is **optional** (an old `{enabled}`-only blob reads back with `sound`/`display`/`urgency`/`lastSeenMs`/`name`/`icon` at their defaults) and the field set is **closed** (unknown keys, the stale lock-screen pair, and out-of-vocabulary `display`/`urgency` values are all dropped; a non-numeric or negative `lastSeenMs` reads as 0). Plus: `forgetApp` deleting the key rather than writing an all-defaults rule; `rememberApplication` stamping `lastSeenMs`/`name`/`icon` from the clock; `effectiveUrgency` and all four of its consumers (`playBell`'s low check, `notificationTimeoutMs`'s critical duration, the breakthrough gate, `NotificationCard`'s critical edge); the per-app `sound` switch in `playBell`; `display: "history"` reaching history and unread but not the popup list or the bell; and the popup gate literal `!root.doNotDisturb \|\| FocusModes.allows(appId) \|\| breaksThrough` with `breaksThrough` being `Settings.criticalBreaksThrough` ANDed with effective-critical. The schema key and its `Settings` reader are pinned too. Page assertions now read the page **and** the components it delegates rows to (`NotificationAppRow.qml`), so pulling the expanded body into a component does not read as the feature being deleted. Runtime: four new fixtures — `historyOnly`, `forgetting`, `urgency`, `breakthrough` — and the two existing jq literals became field-by-field predicates, because `lastSeenMs` is a wall clock that cannot be written down. | **The whole static half was run** against the landed tree and prints PASS. The runtime half is **deferred**. |
| `quickshell/focus-modes-contract` | Every existing pin is untouched and still passes: conditions-not-alarms, the midnight-crossing / malformed / zero-length schedule arithmetic, single DND ownership, the gaming hook reporting rather than silencing, the retired `gamingSilenceNotifications` key staying out of the schema, and the exception list being both consulted and editable. New: `createMode`/`removeMode`/`renameMode`/`moveMode`/`setTriggerKind`/`seedTrigger`/`uniqueId`/`hasMode` by name; a `bun` replay of `seedTrigger` (all five kinds and their seeds, handed-in fields kept, unknown kinds refused with `null` rather than stored) and of `uniqueId` (slugging, suffixing past a taken id, and the `"mode"` fallback); the "order is priority" claim having to appear on the page; and the manual-mode semantics being *preserved* rather than invented — `automatic` still filters manual-only modes out and the fall-through still carries its note. The editable-list needle moved from `NotificationsPage.qml` to the Focus surface (`FocusPage.qml` + `Focus*.qml`), because the chips live in `FocusModeRow.qml`. | **Statically verified end to end**: every grep re-run against the landed files, the schedule arithmetic replayed in `python3`, and the new API block replayed in `bun` — all green. |
| `quickshell/settings-pages-contract` | `Focus` added to the component list (root type `SettingsPage`, no copied Flickable scaffold) and `focus` to the runtime page-routing sweep. The four Notifications sliders and the `zeroLabel: "Never"` rule are unchanged and still hit. | **Static half verified**: `FocusPage.qml`'s root type and the four slider regexes replayed in `python3`. The routing sweep is **deferred** — it starts an isolated shell. |
| `quickshell/settings-jump-contract` | GamingPage's "Open Focus" now has to go through `ShellState.openSettings("focus")`, and assigning `ShellState.settingsPage` by hand is banned there — the old code did exactly that, which skipped `SettingsRoutes.resolve()` and so skipped this contract's own guard entirely. `NotificationCard`'s jump stays `"notifications"` and is unchanged. | **Statically verified** against the landed `GamingPage.qml` and `NotificationCard.qml`. |

### Contracts deliberately left alone

- `quickshell/search-routing-contract` — needed no edit. It derives page files
  from `SettingsShell`'s switch, so `focus` resolved to `FocusPage.qml` the
  moment B landed the case and the Component. Replayed by hand against the
  landed tree: **144 routed settings, 0 violations** with the focus group
  moved.
- `quickshell/settings-window-contract` — enumerates no tabs. It routes
  `displays` and the retired `desktop` id only.
- `quickshell/settings-ownership-contract` — its duplicate-row scan and its
  `groupPages` parse were replayed against the edited `SettingsSearch.qml` and
  still pass.
- `setup/readme-contract` — no contract file added or removed; `find` still
  counts 169 and the README still claims 169.

### Docs updated in the same wave

- `services/SettingsSearch.qml` — `groupPages` `"focus"` moved from
  `"notifications"` to `"focus"`, plus eight hand-written entries: Do Not
  Disturb, Quiet hours, Critical alerts break through, Application
  notification rules, Forget an app's notifications, Per-app notification
  sound, and Banners or history (all → `notifications`), and Focus session
  duration (→ `focus`). Checked against `settings-search-contract`'s fixed
  query list: none of the new labels or details contains any of its queried
  substrings, so no existing top result moves.

### Still open before the run

- **A live bug this wave removed, worth knowing about.**
  `notification-app-rules-contract` used to `perl`-graft a temporary
  `notificationAppRules` schema key into its copy of `PreferenceSchema.qml`,
  from the era before that key shipped. The key ships now, and the graft's
  anchor comment still exists — so the contract was defining it **twice** in
  the copied schema on every run. The graft is gone, replaced by an assertion
  that both `notificationAppRules` and `criticalBreaksThrough` are present.
- `NotificationAppRulesHarness.qml`'s fake notification now spells out
  `urgency`, `expireTimeout` and `hints`. It previously left all three
  undefined, which meant the timeout path and the urgency path were exercised
  in their undefined branch rather than their ordinary one. If a fixture
  behaves differently than expected on the first run, that change is the first
  place to look.
- The `breakthrough` fixture drives `Settings.criticalBreaksThrough` by writing
  the preference and reading the binding back in the same JS call. That is
  synchronous through `DesktopPreferences.set` (it reassigns `values` and bumps
  `revision` before returning), but it has not been observed. If the fixture
  reports `through: 0`, suspect binding timing before suspecting the gate.
- **`focusDurationMinutes` is now editable on two pages**: a `SliderRow` on
  `WorkspacesPage.qml` and segmented chips on `FocusPage.qml`. No contract
  catches it — `settings-ownership-contract` only scans the five schema-bound
  row types and the chips are a `SegmentedRow` reading `DesktopPreferences`
  directly, and `search-routing-contract` only sees `setting:` rows — but it is
  a real ownership violation by `modules/settings/README.md`'s own rule. Decide
  before the run: either the Workspaces row goes, or the key's `group` moves to
  `focus` and the mirror gets named in `settings-ownership-contract`.
- **A stale comment in `config/PreferenceSchema.qml`** above
  `focusDurationMinutes` still says "The focus group routes to Notifications,
  which is where focusModes renders." It routes to `focus` now. Left for the
  schema's owner rather than edited across agent lines.
- Run order for the sweep: `focus-modes-contract` first (pure static, no
  compositor and no shell), then `settings-jump-contract` and
  `search-routing-contract` (also static), then
  `notification-app-rules-contract` (private D-Bus, isolated shell), and
  `settings-pages-contract` last — it starts an isolated Quickshell beside the
  live one and its own cleanup is what protects the running session.
- Nothing here plays a sound on purpose, but every delivery fixture reaches
  `playBell`, which shells out through `SoundFeedback.playCommand`. That was
  already true of the existing `exercise` fixture; the new fixtures add four
  more chances for it. Keep the harness free of anything that turns the volume
  up.

## Phase 8 (Input) — append below

Spec: `2026-08-24-input-redesign.md`. Keyboard, Mouse & Touchpad and Dictation
were rebuilt around keycaps, dropdowns and a searchable shortcuts browser, and
seven new compositor-backed preference keys landed with them.

**Nothing here was run against a live harness.** Three agents edited the tree
concurrently. What *was* verified is listed per contract below: `bash -n` on
every changed contract, the two source-only contracts run end to end, and the
three compositor-shape contracts replayed offline — `hyprctl descriptions` and
`hyprctl getoption` are read-only queries, so their answers were captured once
and the contract logic replayed against that snapshot with a stub on `PATH`,
never against the running compositor mid-edit.

### New contracts (0)

None. The redesign added rows, components and schema keys to surfaces that
already had contracts, so the README count line stays at **169** and
`setup/readme-contract` needs nothing. (`find` counts 169; the README says 169.)

### The seven new schema keys, per key

Each had to satisfy three contracts at once. Replayed against the landed
`PreferenceSchema.qml`, `hypr/input.lua` and a captured `hyprctl` snapshot:

| Key | Hyprland option | enum-hypr-map | schema-hypr-shape | hypr-prefs |
|---|---|---|---|---|
| `focusOnClose` | `input:focus_on_close` | **PASS** — enum, all three published values offered | **PASS** — `readAs: "int"`, answers `int` | **PASS** — `prefs.getInt("focusOnClose", 0)`, def 0 |
| `scrollMethod` | `input:scroll_method` | **PASS** — string enum, every offered word in the published list | **PASS** — `readAs: "str"`, answers `str` | **PASS** — `prefs.get("scrollMethod", "")`, def `""` |
| `scrollButton` | `input:scroll_button` | n/a — `type: "int"`, not an enum | **PASS** — `readAs: "int"`, answers `int` | **PASS** — `prefs.get("scrollButton", 0)`, def 0 |
| `cursorHideWhileTyping` | `cursor:hide_on_key_press` | n/a — bool | **PASS** — `readAs: "bool"`, answers `bool` | **PASS** — def false |
| `cursorWarpOnWorkspaceChange` | `cursor:warp_on_change_workspace` | n/a — bool over an int option, so the enum rule does not reach it | **PASS** — `readAs: "int"`, answers `int` | **PASS** — `prefs.getInt(..., 0)` vs schema `false`; the contract's own true/false→1/0 normalization is what makes those agree |
| `touchpadClickfinger` | `input:touchpad:clickfinger_behavior` | n/a — bool | **PASS** — `readAs: "bool"` | **PASS** — def false |
| `touchpadTapAndDrag` | `input:touchpad:tap-and-drag` | n/a — bool | **PASS** — `readAs: "bool"` | **PASS** — def true |

Two of those are decisions, not just passes, and both are recorded in the
schema itself:

- `focusOnClose` was specced as a two-way choice. The compositor publishes
  three (`{"mru":2},{"cursor":1},{"next":0}`) and **0 is what this desktop runs
  today**, so a two-option dropdown would have hidden the shipped default from
  its own control. enum-hypr-map-contract fails an enum that drops a published
  value, and would have caught it — verified by deleting value 0 from a copy of
  the schema and watching it fail with exactly that message.
- `cursorWarpOnWorkspaceChange` is a switch over an option with three states.
  `force` (2) is deliberately unreachable from Settings. enum-hypr-map governs
  enums only, so nothing fails — which is the point of writing it down here.

### Updated contracts (6)

| Contract | What it now pins | Verified |
|---|---|---|
| `quickshell/enum-hypr-map-contract` | **String-valued enums are now checked at all.** The parser only ever collected numeric `value:`s, so `accelProfile`, `masterOrientation`, `masterNewStatus` and `windowLayout` were silently skipped and `scrollMethod` would have been too. String options carry no `map`; Hyprland states their accepted words inside the description (`[2fg/edge/on_button_down/no_scroll]`), so those are parsed and checked **one way only**: an offered value the compositor does not name fails; a named value Settings does not offer does not, because that is a product decision (`accel_profile`'s `custom` needs a `scroll_points` curve and is a stated non-goal). Empty string is always allowed — it is how a schema entry says "leave the compositor's default", which is what `[[EMPTY]]` reads back as. Options with no bracket list print a line saying so and are skipped rather than failing. The numeric rules are untouched. | **Replayed offline** against a captured `hyprctl descriptions` (353 options) and the landed schema: PASS, 11 mapped enums (was 9). Both new failure directions exercised on a scratch copy — dropping `focus_on_close`'s value 0 fails, offering `"two_finger"` for `scroll_method` fails. |
| `quickshell/xkb-presets-contract` | Rewritten for the Advanced disclosure. The raw `keyboardOptions`, `keyboardVariant` **and `keyboardLayout`** fields must still be editable on the Keyboard page — matched as blocks, not one-liners, so nesting them inside an expander is fine — and **collapsed-but-present passes while absent fails**: the section must be named ("Advanced") and some `onClicked`/`onTriggered`/`onToggled` handler must actually open it, and no raw field may be pinned `visible: false`. XKB *values* stay pinned exactly (`caps:escape_shifted_capslock`, `caps:ctrl_modifier`, `compose:ralt`, `grp:win_space_toggle`) because moving one changes somebody's keyboard; row *labels* are now matched loosely and case-insensitively, because "Compose key" → "Compose" is a wording decision. The category-preservation rule, both helper signatures, and the three `input.lua`/schema default needles are unchanged. | **Run end to end** against the landed tree — it is source-only and touches neither compositor nor shell. PASS. Nested-block matching and the "no handler ⇒ fail" direction both exercised. |
| `quickshell/keybinds-contract` | A static presentation half ahead of the existing live count check, which a wall of 130 rows and a searchable browser pass identically. Page and `ShortcutRow.qml` are read as one source, so moving a control between them is not a failure: `Keybinds.grouped()` is what supplies the group order, `KeycapChord` is what draws chords, the filter exists and is case-insensitive and matches on `description`, a filtered list says how many of how many it is `showing`, the header count comes from `Keybinds.binds.length`, and the note explaining why there is no GNOME keyboard handoff survives. Count-match, description-completeness and chord-rendering rules are untouched. | **Static half replayed** against the landed `ShortcutsPage.qml` + `ShortcutRow.qml`: all needles hit. The compositor half is **deferred** — it boots a Quickshell harness. |
| `quickshell/keybind-rebind-contract` | UI needles added to the static half (the one that already runs under `PANAMA_KEYBINDS_STATIC_ONLY=1`). Page + row read as one source: `ShortcutCapture` is still what reads key presses (a page that grew its own handler would capture SUPER as a bind of its own), `boundTo` is called **before** `rebind` on the source line order, Change/Reset/`resetBind`/`resetAll`/`isOverridden` all still exist, binds are identified by `luaChord`, and no `rebind`/`resetBind` call is keyed by `description` — the regression that once moved every bind sharing one and cost the XF86Calculator key. The restore-all row and its live differs-count are pinned on the page. Engine needles and the whole live half are untouched. | **`PANAMA_KEYBINDS_STATIC_ONLY=1` run against the landed tree: PASS (static).** All 20 needles individually replayed. Live half **deferred**. |
| `quickshell/settings-pages-contract` | `Shortcuts` and `Mouse` added to the root-type/no-copied-Flickable sweep (neither page was ever in it), `mouse` added to the runtime routing sweep, and a hand-written check that all seven new keys render on `MousePage.qml` — by `setting: "key"` *or* by `commitPreference("key"`. That second spelling is why it is hand-written: dropdowns now render through `OptionPickerRow`, which takes label and options from `PreferenceSchema.spec()` and commits by name, and **has no `setting:` property at all**. Existing Home/Bar/Notifications/ScreenIntelligence pins unchanged. | **Static half run: PASS.** Routing sweep **deferred** — it starts an isolated Quickshell beside the live one. |
| `setup/dictation-contract` | **Every "where text lands" pin is unchanged and none of them conflicts with the on-page test.** They live on `panama-dictate` and `keybinds.lua` — `is_speech` rejecting `[BLANK_AUDIO]`, the guard actually being called before typing, the newline collapse, `wtype` tried before `wl-copy`, one press bind and one release bind — and nothing in them constrains which window has focus. The Try-it field sends the same `start`/`stop` the hotkey sends and merely holds keyboard focus while `wtype` types. What is new is two needles for the risk the test flow *did* introduce: the page must not spell out `scripts/panama-dictate` (the service publishes that path once, and a second copy would go stale silently, since the page's status readout comes from the service and would still be right), and a page that runs a `Process` must go through `Dictation.helper`. | **Run end to end** — it is greps plus a `python3` import of the helper, no compositor and no shell. PASS, including both new needles against the landed `DictationPage.qml`. |

### Verified against the new tree, no edit needed

- `quickshell/schema-hypr-shape-contract` — derives everything from
  `option: "...", readAs: "..."` pairs in the schema, so the seven new keys
  entered it the moment they landed. All seven extract cleanly and all seven
  `readAs` values match what `hyprctl -j getoption` answers with. Two were easy
  to get wrong and are worth naming: `cursor:warp_on_change_workspace` answers
  `int` despite being a switch in the UI, and `input:scroll_method` answers
  `str` despite the neighbouring `scroll_button` answering `int`.
- `tests/hypr/hypr-prefs-contract` — pure static, and **run**: ok, 77
  compositor-owned keys read at config time, up from 70. All seven new keys
  have a `prefs.get()`/`prefs.getInt()` in `config/dot/hypr/input.lua` with a
  fallback equal to the schema default.
- `quickshell/gnome-handoff-contract` — needle-free by construction (it derives
  both sides). **Run**: ok, 14 handoffs checked against 39 pages. The Keyboard
  page still has no GNOME handoff and still explains why.
- `quickshell/schema-hypr-shape-contract`, `tests/hypr/hypr-prefs-contract` and
  `quickshell/gnome-handoff-contract` are the three above. `setup/readme-contract`
  is a fourth: no contract file was added or removed, `find` still counts 169,
  and the README still claims 169.

### Docs updated in the same wave

- `services/SettingsSearch.qml` — three hand-written entries: **Rebind a
  shortcut** (→ `shortcuts`), **Pointer test area** and **Connected input
  devices** (→ `mouse`). "Key repeat" and "Scroll method" arrive automatically
  from the schema, as the spec expected. Checked against
  `settings-search-contract`'s fixed query list: of its 27 pinned queries only
  `pointer` matches any new entry, and "Pointer test area" sorts *after*
  "Pointer focus", "Pointer size" and "Pointer speed" in the same prefix rank,
  so no pinned top result moves. Both new pages are leaves in
  `SettingsRoutes`, so the "routes to a page anyone can land on" sweep holds.
- No settings docs or launcher commands were regenerated here — that is the
  orchestrator's step after the schema settled.

### Still open before the run

- **`settings-ownership-contract` and `search-routing-contract` are now blind
  to dropdown rows.** Both scan for `setting: "…"` inside a fixed list of row
  types; `OptionPickerRow` is in neither list and carries no `setting:`
  property. `accelProfile`, `followMouse`, `focusOnClose` and `scrollMethod`
  are all invisible to them on the rebuilt `MousePage.qml`. Nothing fails
  today — none of those keys is a duplicate — but a duplicate introduced
  through a dropdown would not be caught. `settings-pages-contract` now pins
  the seven new keys directly as a stopgap; the real fix is teaching both
  scans the `PreferenceSchema.spec()` / `commitPreference()` spelling. Owner:
  whoever holds those two contracts next.
- **`xkb-presets-contract` now requires a raw `keyboardLayout` field**, on the
  reading that the layout dropdown's "Custom…" has to reveal somewhere the
  code can actually be typed. It passes against the landed page. If the layout
  editor is ever folded into the dropdown itself, that needle is the one to
  revisit — the intent is "the raw code stays typeable", not "it is a
  TextEntryRow".
- **`keybinds-contract` pins the literal word `showing`** in the filtered-count
  line, because the spec names that wording ("showing N of M"). It is the one
  prose needle in the new static half; everything else keys on structure.
- **Dictation's Try-it field and the clipboard fallback** — handled, but worth
  knowing. `panama-dictate` falls back to `wl-copy` when `wtype` is missing, by
  design, and on the Try-it row that means the words land on the clipboard
  rather than in the field the page just focused. The page says so: a "Typing —
  Missing" row appears when `Dictation.typingAvailable` is false. Nothing to
  fix; worth a look during the run if a machine without `wtype` is around, since
  that branch has never been seen.
- Run order for this phase: the two source-only contracts first
  (`xkb-presets-contract`, `gnome-handoff-contract`), then the static halves
  (`hypr-prefs-contract`, `PANAMA_KEYBINDS_STATIC_ONLY=1 keybind-rebind-contract`,
  `PANAMA_SETTINGS_STATIC_ONLY=1 settings-pages-contract`), then the two
  compositor-query contracts (`enum-hypr-map-contract`,
  `schema-hypr-shape-contract` — read-only, but they want the real compositor),
  then the harness contracts (`keybinds-contract`, `keybind-rebind-contract`
  in full, `settings-search-contract`), and `settings-pages-contract` last, as
  before: it starts an isolated Quickshell beside the live one and its own
  cleanup is what protects the running session.
- `keybind-rebind-contract`'s live half rebinds Terminal to `SUPER + SHIFT +
  F9` against the **real compositor** with an isolated `XDG_CONFIG_HOME`. That
  was true before this phase and is unchanged, but it is the one contract in
  this wave that writes to the running keymap, so it wants a quiet moment.

## Phase 9 (Network & Sharing) — append below

Spec: `2026-08-24-network-sharing-redesign.md`. Connections became a full
network manager (per-connection details, forget, autoconnect, MAC
randomization, VPN import, hotspot, enterprise Wi-Fi, airplane mode, system
proxy), Firewall grew its add side and a zone browser, Printers gained per-
printer defaults and job hold/release, and Sharing got copy and structure work.
The last two GNOME punt rows in the app died with the "Owned by Fedora" card.

**Nothing here was run against a live harness.** Three agents edited the tree
concurrently. What *was* verified is listed per contract below.

### New contracts (1)

`quickshell/network-tools-contract`. The README count line moves **169 → 170**;
`setup/readme-contract` was run and passes ("170 contracts, as documented"),
counted the same way `panama test` collects the suite.

### Verified

- **`quickshell/network-tools-contract` — RUN END TO END, PASS.** It is safe to
  run because it never reaches the machine: `env -i` with a stub directory first
  on `PATH`, stubs for nmcli/gsettings/rfkill plus every D-Bus client, a
  PyGObject stand-in on `PYTHONPATH` whose `require_version` always raises, and
  both D-Bus bus addresses pointed at sockets that do not exist. It asserts the
  first two of those before running the helper at all, and refuses to continue
  if `nmcli`, `gsettings` or `rfkill` resolves anywhere but the stub directory.
  Checked with a debug copy that it is doing real work rather than passing
  vacuously: the stub's terse listing drives the shipped parse all the way to
  `{"ip4":"192.168.7.42/24","gateway":"192.168.7.1","dns":["192.168.7.1",
  "1.1.1.1"],"mac":"AA:BB:CC:DD:EE:FF","macRandomized":true,…}` while the three
  secret properties in the same listing are absent from it.
  - The libnm/D-Bus branch of `join-enterprise` is deliberately **not**
    exercised — running it would add a real connection profile. It is covered
    statically instead, by an AST walk that fails if any command list in the
    helper carries a password-shaped identifier. The nmcli fallback is what the
    dynamic half drives, and there the password is asserted present on the
    editor's **stdin** and absent from **argv**, stdout, stderr and disk.
- **`quickshell/connectivity-contract` — static half run, and it found a bug.**
  See "Still open" below. The new enum check reads the member list out of the
  installed `quickshell-network.qmltypes` rather than a hand-kept list, so it
  cannot drift the way the two bugs it catches did.
- **`quickshell/firewall-contract` — static half run, PASS** (everything up to
  the first live `firewall-cmd` read).
- **`quickshell/printers-contract` — static half run, PASS.**
- **`quickshell/sharing-contract` — static half run, PASS.**
- **`quickshell/gnome-handoff-contract` — RUN END TO END, PASS** (source-only):
  "ok (12 handoffs checked against 39 pages)" with `network` and `wifi` now in
  OWNED.
- **`quickshell/health-ui-contract` — static half run, PASS.**
- **`PANAMA_SETTINGS_STATIC_ONLY=1 settings-pages-contract` — PASS.**
- **`setup/readme-contract` — RUN END TO END, PASS.**
- `bash -n` on every changed contract; every embedded `python3` heredoc compiled
  separately with `py_compile`.

### Still open before the run

- **`Connectivity.qml:204` names an enum member that does not exist.**
  `ConnectionFailReason.Authentication` is not a member; the real ones are
  `NoSecrets`, `Unknown`, `WifiAuthTimeout`, `WifiClientDisconnected`,
  `WifiClientFailed`, `WifiNetworkLost`. QML resolves it to `undefined`, the
  switch arm never matches, and a wrong password is reported with the
  fallthrough text. `NoSecrets` is almost certainly the intended member.
  `connectivity-contract`'s new enum check fails on exactly this line and passes
  on a copy with it corrected, so the check is confirmed working and the fix is
  a one-word edit in a service file this phase's contract owner does not own.
  **This is the one item blocking a clean run.**
- **The enum check is scoped to `Connectivity.qml`.** The same class of bug —
  a plausible enum member that does not exist, resolving to `undefined` in
  silence — can live anywhere that imports `Quickshell.Networking`, including
  `modules/quicksettings/WifiList.qml` and the bar's status cluster. Widening
  the sweep to every QML file that imports the module is a small change and the
  obvious next one. Owner: whoever holds `connectivity-contract` next.
- **`network-tools-contract` cannot see the libnm branch.** That is a deliberate
  trade, but it means the branch that actually runs on this machine (NM 1.56,
  bindings present) is only ever checked by reading. A machine without PyGObject
  would exercise the fallback for real; nothing here has one.
- **Two contracts still pin prose.** `firewall-contract` requires the add flow
  to say "permanent" and "ask for your password", and `sharing-contract`
  requires "never passes through Panama", "install it and this becomes a switch"
  and "does not install software". The spec names all five phrases, so they are
  pinned deliberately, but they are the needles a copy edit will trip.
- **`printers-contract` pins the option vocabulary exactly** — `media` ∈
  {Letter, A4, Legal}, `sides` ∈ {one-sided, two-sided-long-edge,
  two-sided-short-edge}. Adding a third settable option is meant to be a
  deliberate act that updates this contract, but it will read as a surprise the
  first time somebody tries.
- **`connectivity-contract`'s live half is unchanged** and still starts a
  harness beside the running session, so it wants the same quiet moment it
  always did. `PANAMA_CONNECTIVITY_STATIC_ONLY=1` runs the new source-only half
  alone.
- Run order for this phase: the source-only contracts first
  (`gnome-handoff-contract`, `PANAMA_NETWORK_STATIC_ONLY=1
  network-tools-contract`, `PANAMA_CONNECTIVITY_STATIC_ONLY=1
  connectivity-contract`, `PANAMA_SETTINGS_STATIC_ONLY=1
  settings-pages-contract`, `setup/readme-contract`), then
  `network-tools-contract` in full — it is hermetic, so it can run at any time —
  then the read-only system contracts (`firewall-contract`,
  `printers-contract`, `sharing-contract`), then the harness contracts
  (`connectivity-contract`, `health-ui-contract`, `settings-search-contract`),
  and `settings-pages-contract` last, as before.

### Docs updated in the same wave

- `services/SettingsSearch.qml` — the three "Managed by GNOME Settings"
  connectivity entries are gone, and with them the duplicate **Printers** entry
  that routed to `connectivity` rather than to the Printers page. Ten entries
  replace them, all routing to `connectivity`: **Wi-Fi**, **Bluetooth**, **VPN**,
  **Import a VPN**, **Hotspot**, **Airplane mode**, **Network proxy**, **IP
  address**, **Forget a Wi-Fi network**, **Enterprise Wi-Fi**. Wi-Fi and
  Bluetooth were rewritten rather than deleted: the spec lists eight additions,
  none of which contains the word "Bluetooth", so deleting the lying entry
  outright would have made a switch the page has unreachable by search.
- Checked against `settings-search-contract`'s pinned query list: none of its 21
  ranked queries, nor the nine leaf-routing queries, matches any new or changed
  entry, so no pinned top result moves. `connectivity` is a leaf in
  `SettingsRoutes`, so the routing sweep holds.
- No settings docs or launcher commands were regenerated: this phase added no
  schema keys, so there is nothing for `panama-settings-docs` or
  `panama-settings-commands` to pick up. Verified by reading the diff — every
  new setting here is system state (NetworkManager, firewalld, CUPS, gsettings),
  not a Panama preference.

## Phase 10 (Applications, Storage & Snapshots) — append below

Spec: `2026-08-24-applications-storage-snapshots-redesign.md`. Applications
became an app manager (installed list with search, Flatpak uninstall, permission
summaries, per-app autostart, jump chips, the `panama apps` catalog rendered
natively, role dropdowns plus a single-type override). Storage grew a
proportional breakdown bar and an itemized "Clean up, honestly" card, and lost
the duplicate container-images row that opened a terminal. Snapshots made
retention editable and moved the file browser into its own card, which fixes
"browse from a collapsed volume card does nothing".

Three agents edited the tree concurrently. Everything below was reconciled
against the landed files at the end of the phase rather than against the spec's
pinned shapes.

### New contracts (1)

`quickshell/app-library-contract`. The README count line moves **170 → 171**;
`setup/readme-contract` was run and passes ("171 contracts, as documented").

### Run and passing

These four are hermetic or source-only, so they were run rather than deferred:

- **`quickshell/app-library-contract` — RUN END TO END, PASS.** Safe to run
  because it never reaches the machine: `env -i`, a stub directory first on
  `PATH`, recording stubs for flatpak/rpm/pkexec and screaming stubs for
  dnf/yum/sudo/rpm-ostree/gio, `HOME` and every XDG directory inside the scratch
  tree, and a fixture catalog through `PANAMA_EXTRAS_DIR`. It asserts, before
  running the helper at all, that the helper names no binary by absolute path
  and that all six commands resolve inside the stub directory. What it pins:
  - **Catalog agreement.** `setup/lib/extras-catalog`'s bash functions and the
    helper's Python parser are both run over the same fixture files and their
    answers compared entry by entry — id, label, kind — rather than either being
    read. The fixture exercises the format's corners: a labelled entry, an
    unlabelled Flathub id (label derived from the last dotted component), a bare
    dnf name, a `|`-labelled dnf name, comments, blank lines, and two indented
    continuation lines that must fold into the entry above.
  - **Ids are the catalog line verbatim.** `flatpak:org.example.Bravo`, not the
    stripped ref: the bare ref is in the refusal list, because handing that to
    `install` would be refused for every Flathub entry in the real catalog and
    the failure would read as "installing is broken".
  - **Nothing off-catalog installs**, and the empty command log is what proves
    the refusal came first. Off-catalog ids, an unknown category, a path
    escaping the catalog directory, a continuation line, and an entry that
    exists in the *other* category are all refused with nothing run.
  - **Extensions ride with their entry and nothing else does** (installing Echo
    reaches for Echo and its two plugins, and no other `org.example.*`).
  - **Removal is flatpak-only**, pinned three ways: an AST walk that fails if
    any command list in the helper pairs dnf/yum/rpm-ostree with a removal verb
    or invokes rpm for anything but a query; a second AST walk over `uninstall`
    itself; and a runtime check that no argument — including a dnf package name
    — produces a package-manager call.
  - **Permission buckets from data**: `filesystems=host` → "Full file system
    access" and `filesystems=home` → "Home folder" are checked against separate
    fixtures so the two cannot be conflated; `devices=all` → Camera,
    `sockets=pulseaudio` → Microphone, `shared=network` → Network; an
    unrecognized key must still appear in the output; and a sandboxed
    application must summarize strictly shorter than a permissive one, so the
    summary cannot be a constant.
- **`quickshell/applications-settings-contract` — RUN END TO END, PASS**
  (source-only). The bun-extracted `roles` / `matchesRole` half survives B's
  rebuild verbatim and gained four fixtures, including the two shapes that once
  made Archives match nothing: categories arriving as a QML list, and as a
  comma-separated string.
- **`quickshell/default-apps-contract` — RUN END TO END, PASS.** Already
  fixture-driven (its own XDG tree, stub `xdg-mime`/`xdg-settings`); the new
  half adds a fixture `mime/globs2` and two desktop entries that declare
  `MimeType`, then pins `search-types` shape, that candidates are only installed
  applications, that a one-character query is not a search, that `set-type`
  writes exactly one type, and that an unknown type, an unknown application, and
  a type this system does not have are each refused with nothing reaching
  xdg-mime.
- **`setup/readme-contract`, `quickshell/search-routing-contract`,
  `quickshell/settings-ownership-contract` — RUN, PASS** after the nine new
  search entries.

### Extended contracts, new halves run in isolation (3)

`disks-contract` and `snapshots-contract` each keep a first half that reads the
live machine (`panama-disks snapshot`, `panama-snapshots snapshot`), so neither
was run end to end. The **new** halves were extracted into scratch scripts and
run on their own, and both pass:

- **`quickshell/disks-contract`** (new half run, PASS). It is hermetic: `env -i`,
  `HOME` and `XDG_CACHE_HOME` inside the scratch tree, the block tree from
  `PANAMA_DISKS_LSBLK`, and recording stubs for gio/flatpak/pkexec/dnf/podman.
  - **Two proofs run before anything is cleaned**: `breakdown.path` must be the
    fixture home, and the cache segment must be the 12 × 111111 bytes this
    contract wrote a moment earlier. Only then is `clean cache` allowed to run —
    which is what makes it safe to assert that the symlink planted inside the
    fixture cache was unlinked rather than followed, and that the file it points
    at outside the cache survived.
  - **The arithmetic**: home + applications + caches + system == `usedBytes`
    exactly, `free` == `freeBytes`, every segment non-negative, and
    `exceedsUsed` false on the fixture. The two ways the measurement can be
    wrong (`complete === false`, `exceedsUsed === true`) are pinned as things
    the page says out loud.
  - **The anti-racket stance**, pinned as an absence in the cleanup card's own
    string literals: no "running out", "recommended", "act now", "junk", "safe
    to remove", "you should", no exclamation marks, and no single button that
    clears everything. The extractor takes the *tightest* card whose own title
    is the cleanup one, and scans only double-quoted literals — QML is full of
    `!` and none of it is shouting.
  - **Each cleanable does its own one thing**: `gio trash --empty` (never rm),
    `flatpak uninstall --unused --noninteractive`, and
    `pkexec dnf clean packages` — never `clean all`, never a removal. An AST
    walk pins that this is the *only* package-manager command in the whole
    helper.
  - **The unused-runtime size is borrowed, not recomputed**: with
    `PANAMA_APPLICATIONS_HELPER` pointed at a recording stub, the row must
    report what that stub said (780000) and the stub must have been asked. Two
    ideas of "unused" would show one number and free another.
  - `backing_device` reading findmnt's SOURCE rather than `st_dev` is pinned
    with the reason: btrfs gives every subvolume its own device number, and the
    first version of the breakdown lost the system-wide flatpak installation to
    exactly that.
- **`quickshell/snapshots-contract`** (new half run, PASS). Retention is
  exercised against a recording `snapper` stub under `env -i`, after asserting
  snapper resolves inside the stub directory — the only way to run a write verb
  without changing how this machine keeps its snapshots.
  - Refusals here are read from the JSON `error` field, not an exit code: this
    helper answers a refusal with fresh state and an `error` in it. Whether a
    refusal happened *first* is read from the absence of a `set-config` in the
    log, because the helper reads the configuration list on its way back out
    either way.
  - Ceiling pinned at **50 in both places** — the helper's `RETENTION_LIMIT` and
    the service's `retentionMax` — because a dropdown offering a value the
    helper refuses fails after the user has already chosen.
  - The browser-card fix is pinned structurally: a brace-aware scan (strings and
    comments skipped) walks the QML ancestry of `Snapshots.browseEntries` and
    fails if the enclosing card is a delegate of the per-volume Repeater. This
    was checked against the OLD page first, where it correctly fails, so it is
    not a check that passes on anything.

### Docs updated in the same wave

- `services/SettingsSearch.qml` — nine entries added, all routing to leaves that
  exist in `SettingsRoutes`: **Installed applications**, **Uninstall an
  application**, **Application permissions**, **Install applications**,
  **Autostart**, **File associations** → `applications`; **Clean up storage**,
  **Application caches** → `storage`; **Snapshot retention** → `snapshots`.
  Checked by evaluating the array: 154 entries, no duplicate labels, every
  `page` a real leaf, and none of `settings-search-contract`'s 21 ranked queries
  or 9 leaf-routing queries matches a new entry, so no pinned top result moves.
  (The first draft of the Snapshot retention detail said "each volume keeps",
  which put it in the result set for the pinned `volume` query; reworded.)
- No settings docs regenerated: this phase adds no schema keys. Every new
  setting is system state (flatpak, dnf, snapper, xdg-mime), not a Panama
  preference — verified by reading the diff.

### Still open before the run

- **`disks-contract` and `snapshots-contract` have not been run end to end.**
  Their first halves read the live machine, so they want the same quiet moment
  the other system contracts do. Nothing in the new halves depends on that
  order.
- **`settings-search-contract` has not been run**: it starts a Quickshell
  harness. The nine new entries were checked statically as described above, but
  the schema-label sweep and the ranked queries need the live harness.
- **`settings-pages-contract`, `settings-docs-contract`, `settings-jump-contract`
  and `settings-buttons-contract` were not run against the three rebuilt pages.**
  ApplicationsPage grew four new components (InstalledAppRow, FileTypePicker,
  SettingsChip, StorageBreakdownBar); the qmldir registration of the first three
  is pinned by `applications-settings-contract`, but nothing here has loaded the
  QML.
- **`app-library-contract` pins the fixture seam `PANAMA_EXTRAS_DIR` and the
  permission bucket wording** ("Camera", "Microphone", "Full file system
  access", "Home folder", "Network", "Devices"). Both match the landed helper;
  changing either is meant to be a deliberate act that updates this contract,
  and will read as a surprise the first time somebody tries.
- Run order for this phase: the hermetic and source-only ones first
  (`app-library-contract`, `applications-settings-contract`,
  `default-apps-contract`, `search-routing-contract`,
  `settings-ownership-contract`, `setup/readme-contract`), then the read-only
  system ones (`disks-contract`, `snapshots-contract`, `containers-contract`),
  then the harness ones (`settings-search-contract`, `health-ui-contract`), and
  `settings-pages-contract` last, as before.
