Build the Panama Hyprland desktop

docs/superpowers/plans/2026-08-17-contextual-signal-glass.md

@@ -0,0 +1,94 @@
+# Contextual Signal Glass 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:** Build a curated event broker, quiet shared Signal Glass host, and persistent privacy/activity indicators.
+
+**Architecture:** Producers publish structured events to one bounded broker. A single per-screen host renders transient events ahead of existing focus controls, while persistent privacy state renders independently in the bar.
+
+**Tech Stack:** Quickshell QML, QtQuick, Quickshell PipeWire/Bluetooth/Io APIs, Hyprland, Bash contract tests
+
+**Spec:** `docs/superpowers/specs/2026-08-17-contextual-signal-glass-design.md`
+
+## Global Constraints
+
+- Initial discovery must not emit user-visible events.
+- DND suppresses ambient events but never persistent privacy state.
+- No idle visual animation or unbounded queue/process loop.
+- Existing Focus behavior and tests must remain compatible.
+
+---
+
+### Task 1: Status event broker
+
+**Files:**
+- Create: `config/dot/quickshell/services/StatusEvents.qml`
+- Modify: `config/dot/quickshell/shell.qml`
+- Test: `tests/quickshell/status-events-contract.sh`
+
+**Interfaces:**
+- Produces: `publish(event: var)`, `dismiss(): void`, `invoke(): void`, `activeEvent`, `active`, and IPC diagnostics.
+
+- [ ] Write an IPC contract that publishes ambient and critical fixtures, verifies replacement and DND filtering, and dismisses cleanly.
+- [ ] Run the contract and verify it fails because the IPC target is absent.
+- [ ] Implement broker normalization, priority, four-entry queue, stable-key replacement, expiry, and action routing.
+- [ ] Wire a diagnostics-only IPC target and run the contract to green.
+
+### Task 2: Shared Signal Glass host
+
+**Files:**
+- Create: `config/dot/quickshell/modules/signals/SignalGlass.qml`
+- Create: `config/dot/quickshell/modules/signals/EventCard.qml`
+- Create: `config/dot/quickshell/modules/signals/FocusCard.qml`
+- Create: `config/dot/quickshell/modules/signals/qmldir`
+- Modify: `config/dot/quickshell/shell.qml`
+- Retire: `config/dot/quickshell/modules/focus/FocusCapsule.qml`
+
+**Interfaces:**
+- Consumes: `StatusEvents.activeEvent`, `FocusSession.active`, and `FocusSession.capsuleVisible`.
+- Produces: one `qs-signal-glass` layer surface per monitor.
+
+- [ ] Add a static source contract proving only one Signal Glass host is instantiated.
+- [ ] Extract the existing focus presentation without changing its actions.
+- [ ] Implement the compact event presentation and event-first/focus-second arbitration.
+- [ ] Verify focus contracts and QML construction.
+
+### Task 3: Event producers and persistent activity
+
+**Files:**
+- Create: `config/dot/quickshell/services/PrivacyState.qml`
+- Create: `config/dot/quickshell/services/DeviceEvents.qml`
+- Modify: `config/dot/quickshell/services/Capture.qml`
+- Modify: `config/dot/quickshell/services/NightLight.qml`
+- Modify: `config/dot/quickshell/services/FocusSession.qml`
+- Test: `tests/quickshell/activity-state-contract.sh`
+
+**Interfaces:**
+- Produces: `PrivacyState.microphoneActive`, `cameraActive`, `screenSharingActive`, `recordingActive`, `activeKinds`, and transition events.
+
+- [ ] Write contracts for capture events and independent persistent-state reporting.
+- [ ] Instrument Panama-owned capture, Night Light, and focus completion transitions.
+- [ ] Add initialized transition monitoring for output, Bluetooth, KDE Connect, and privacy activity.
+- [ ] Run the contracts and verify missing optional integrations fail quietly.
+
+### Task 4: Bar indicator and detail panel
+
+**Files:**
+- Create: `config/dot/quickshell/modules/bar/ActivityIndicator.qml`
+- Create: `config/dot/quickshell/modules/bar/ActivityPanel.qml`
+- Modify: `config/dot/quickshell/modules/bar/Bar.qml`
+- Modify: `config/dot/quickshell/services/ShellState.qml`
+
+**Interfaces:**
+- Consumes: `PrivacyState` booleans and `Capture.stopRecording()`.
+
+- [ ] Add the indicator beside Focus with semantic icon/color selection.
+- [ ] Add a compact details popover and safe Stop action for Panama recording.
+- [ ] Verify overlay exclusivity, click targets, and all active-state combinations.
+
+### Task 5: System verification
+
+- [ ] Run all Quickshell contract tests.
+- [ ] Run QML/runtime diagnostics and inspect logs for warnings.
+- [ ] Capture ambient, privacy, recording, and focus-restoration states.
+- [ ] Restart the live Quickshell instance and repeat the smoke contract.

docs/superpowers/plans/2026-08-17-continuum-scratchpad.md

@@ -0,0 +1,82 @@
+# Continuum Scratchpad and Window Actions 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:** Add address-scoped close and drag/drop workspace movement plus a global visual scratchpad shelf to Continuum.
+
+**Architecture:** Window components emit intent; OverviewBody owns Hyprland dispatches. Workspace cards and the shelf are drop destinations, and the special scratch workspace remains separate from the positive-workspace filmstrip.
+
+**Tech Stack:** Quickshell QML, QtQuick Drag APIs, Quickshell.Hyprland, Hyprland dispatchers, Bash contract tests
+
+**Spec:** `docs/superpowers/specs/2026-08-17-continuum-scratchpad-design.md`
+
+## Global Constraints
+
+- Every close and move command must target one normalized window address.
+- Existing click-to-focus, search, and focus-workspace integration must remain intact.
+- `Super+X` and `Super+Shift+X` semantics remain unchanged.
+- Drag feedback is event-driven and stops immediately after drop/cancel.
+
+---
+
+### Task 1: Address-scoped action boundary
+
+**Files:**
+- Modify: `config/dot/quickshell/modules/overview/OverviewBody.qml`
+- Test: `tests/quickshell/overview-window-actions-contract.sh`
+
+**Interfaces:**
+- Produces: `addressOf(toplevel)`, `closeToplevel(toplevel)`, `moveToplevel(toplevel, workspaceName)`, and `restoreToplevel(toplevel)`.
+
+- [ ] Write a static/live contract proving move and close operations include an exact disposable-window address.
+- [ ] Run it and verify the missing IPC/action surface fails.
+- [ ] Implement normalized address helpers and bounded post-dispatch refresh.
+- [ ] Run the contract to green without touching non-disposable windows.
+
+### Task 2: Draggable window chrome
+
+**Files:**
+- Modify: `config/dot/quickshell/modules/overview/WindowThumbnail.qml`
+- Modify: `config/dot/quickshell/modules/overview/WorkspaceCard.qml`
+
+**Interfaces:**
+- Produces: activation, close, drag-start, and drag-finish signals carrying the toplevel.
+- Consumes: workspace drop callback carrying toplevel and target workspace.
+
+- [ ] Add a source contract for hover-only close chrome and drag payload identity.
+- [ ] Implement restrained hover/drag states with activation suppression after drag.
+- [ ] Make workspace cards highlight and accept the exact toplevel payload.
+- [ ] Verify clicking still focuses and dropping leaves Continuum open.
+
+### Task 3: Global scratchpad shelf
+
+**Files:**
+- Create: `config/dot/quickshell/modules/overview/ScratchpadShelf.qml`
+- Modify: `config/dot/quickshell/modules/overview/OverviewBody.qml`
+- Test: `tests/quickshell/scratchpad-shelf-contract.sh`
+
+**Interfaces:**
+- Consumes: Hyprland workspace named `special:scratch` and OverviewBody move/restore callbacks.
+- Produces: always-available scratch drop target and populated live-card shelf.
+
+- [ ] Write a contract confirming the global special workspace and existing keybindings.
+- [ ] Implement the collapsed empty target and expanded populated shelf.
+- [ ] Wire drop-to-hide, click-to-restore, and address-scoped close.
+- [ ] Verify the selected positive workspace remains stable while hiding windows.
+
+### Task 4: Keyboard navigation and visual refresh
+
+**Files:**
+- Modify: `config/dot/quickshell/modules/overview/Overview.qml`
+- Modify: `config/dot/quickshell/modules/overview/OverviewBody.qml`
+
+- [ ] Add workspace Left/Right, result navigation, Enter, Delete, and Escape handling.
+- [ ] Refresh workspace/toplevel models and one-shot captures after successful actions.
+- [ ] Verify keyboard and pointer flows do not double-activate.
+
+### Task 5: System verification
+
+- [ ] Run overview, focus, window-action, and scratchpad contracts.
+- [ ] Use disposable windows to test move, hide, restore, and close end to end.
+- [ ] Capture empty shelf, populated shelf, drop target, and close chrome states.
+- [ ] Restart Quickshell and confirm the overview maps without warnings.

docs/superpowers/plans/2026-08-17-focus-glass-continuum.md

@@ -0,0 +1,115 @@
+# Focus Glass and Continuum Overview 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:** Add a persistent focus-session workflow with a Signal Glass control capsule and replace the current workspace-card overview with the GNOME-like Continuum filmstrip.
+
+**Architecture:** A singleton `FocusSession` service owns all timing and side effects, while focused QML modules render the capsule, bar indicator, Quick Settings entry point, and overview. `ShellState` carries only overlay selection and the requested overview workspace, keeping focus state independent from window state.
+
+**Tech Stack:** Quickshell 0.3.0, Qt 6 QML, Quickshell Hyprland IPC, Quickshell Io `FileView`/`JsonAdapter`, Hyprland 0.56 Lua configuration
+
+**Spec:** `docs/superpowers/specs/2026-08-17-focus-glass-continuum-design.md`
+
+## Global Constraints
+
+- Use the existing Tokyo Night Moon tokens and Prism edge; do not hardcode component colors.
+- Use event-driven transitions only; no continuously repainting visual animations.
+- Keep the current bar edge-to-edge and transparent.
+- Preserve all existing overlay shortcuts and GNOME-derived workspace bindings.
+- Add no package or background daemon.
+- Persist only state transitions; do not write the remaining time every second.
+
+---
+
+### Task 1: Focus-session state machine
+
+**Files:**
+- Create: `config/dot/quickshell/services/FocusSession.qml`
+- Modify: `config/dot/quickshell/config/Settings.qml`
+- Test: temporary standalone Quickshell harness under `/tmp`
+
+**Interfaces:**
+- Consumes: `Notifs.doNotDisturb`, `Caffeine.enabled`, `Hyprland.focusedWorkspace`, `Hyprland.dispatch()`
+- Produces: `active`, `paused`, `capsuleVisible`, `workspaceId`, `workspaceLabel`, `remainingSeconds`, `remainingText`, `start(minutes)`, `startDefault()`, `pauseOrResume()`, `dismiss()`, `reveal()`, `activateWorkspace()`, `end(completed)`
+
+- [x] Add `focusDurationMinutes: 45` to `Settings.qml`.
+- [x] Create a singleton with a wall-clock deadline and paused remaining duration.
+- [x] Persist state atomically to `Quickshell.stateDir + "/focus-session.json"` with `FileView` and `JsonAdapter`.
+- [x] Record and restore the pre-session DND and Caffeine values.
+- [x] Resolve expiry on every one-second timer tick and immediately after state restoration.
+- [x] Run executable contracts for active-to-ended state, pause stability, persisted restart restoration, and completion from an expired persisted deadline.
+
+### Task 2: Signal Glass capsule and compact indicator
+
+**Files:**
+- Create: `config/dot/quickshell/modules/focus/FocusCapsule.qml`
+- Create: `config/dot/quickshell/modules/focus/FocusIndicator.qml`
+- Create: `config/dot/quickshell/modules/focus/FocusAction.qml`
+- Modify: `config/dot/quickshell/modules/bar/Bar.qml`
+- Modify: `config/dot/quickshell/shell.qml`
+- Modify: `config/dot/hypr/rules.lua`
+
+**Interfaces:**
+- Consumes: Task 1's `FocusSession` public properties and functions
+- Produces: a `qs-focus-capsule` layer surface and a clickable bar indicator
+
+- [x] Build the compact indicator as a transparent-bar-native pill showing a focus glyph and tabular remaining time.
+- [x] Build the capsule with a Prism glass surface, primary workspace target, explicit close control, and Pause/Resume, Workspace, and End actions.
+- [x] Make the primary row activate the stored workspace and dismiss only the capsule.
+- [x] Instantiate one capsule and add one indicator to the right-side bar row.
+- [x] Add a focused Hyprland layer rule enabling blur, suppressing compositor animation, and excluding the capsule from screen sharing.
+- [x] Reload Quickshell and verify dismiss/reopen and workspace activation through live state.
+
+### Task 3: Discoverable start paths and IPC
+
+**Files:**
+- Modify: `config/dot/quickshell/modules/quicksettings/QuickSettingsPanel.qml`
+- Modify: `config/dot/quickshell/shell.qml`
+- Modify: `config/dot/hypr/keybinds.lua`
+- Modify: `config/dot/hypr/README.md`
+
+**Interfaces:**
+- Consumes: Task 1's service and Task 2's capsule visibility
+- Produces: Quick Settings Focus row, `focus` IPC target, `SUPER+SHIFT+F` binding
+
+- [x] Add a full-width Quick Settings row that starts the default session while idle and shows the capsule while active.
+- [x] Register typed IPC functions `start()`, `reveal()`, `pause()`, `workspace()`, `overview()`, and `end()`.
+- [x] Bind `SUPER+SHIFT+F` to `qs ipc call focus reveal`, where `reveal()` starts a default session if none exists.
+- [x] Verify every function using `qs ipc call focus ...` and verify the Hyprland config.
+
+### Task 4: Continuum workspace filmstrip
+
+**Files:**
+- Modify: `config/dot/quickshell/services/ShellState.qml`
+- Modify: `config/dot/quickshell/modules/overview/Overview.qml`
+- Modify: `config/dot/quickshell/modules/overview/OverviewBody.qml`
+- Modify: `config/dot/quickshell/modules/overview/WorkspaceCard.qml`
+
+**Interfaces:**
+- Consumes: `FocusSession.workspaceId`, `ShellState.overviewWorkspaceId`, Hyprland workspace and toplevel models
+- Produces: `ShellState.openOverview(workspaceId)`, filmstrip selection, large workspace preview, cross-workspace window search
+
+- [x] Add requested-overview-workspace state without coupling `ShellState` to the focus service.
+- [x] Replace the centred equal-card row with a top filmstrip and a large selected-workspace preview.
+- [x] Keep the trailing dynamic-workspace card and one-shot thumbnail capture behavior.
+- [x] Add wheel navigation over the strip and keep the overview mapped while switching workspaces.
+- [x] Add a keyboard-focused search field and filtered cross-workspace window results.
+- [x] Mark the focus-session workspace subtly in both filmstrip and preview.
+- [x] Verify workspace selection, window activation, scrolling, new workspace creation, search, Escape, and background dismissal.
+
+### Task 5: Integration and visual verification
+
+**Files:**
+- Modify: `config/dot/hypr/DESKTOP-PARITY.md`
+- Modify: `README.md`
+
+**Interfaces:**
+- Consumes: all previous tasks
+- Produces: documented, live daily-driver feature
+
+- [x] Run `Hyprland --verify-config` and reload the Lua configuration.
+- [x] Reload the live Quickshell instance and inspect `qs log` for QML errors and warnings.
+- [x] Exercise a short live focus session through start, pause, resume, dismiss, reopen, workspace overview, and end.
+- [x] Capture screenshots of capsule open, indicator-only, Continuum default, and Continuum search states.
+- [x] Update Panama's feature documentation and keybinding table with the verified behavior.
+- [x] Inspect the exact Panama diff and ensure unrelated pre-existing changes remain untouched.

docs/superpowers/plans/2026-08-17-panama-settings.md

@@ -0,0 +1,128 @@
+# Panama Settings 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:** Build the approved Luminous System Settings control center and map it to `Super+I` while preserving GNOME Settings as a launcher-accessible fallback.
+
+**Architecture:** A persisted `DesktopPreferences` singleton owns user choices, `SystemSettings` owns allow-listed system reads and writes, and a normal tiled Settings window renders focused pages over those boundaries. Existing shell consumers continue through `Settings.qml`, while `ShellState` and typed IPC own window routing.
+
+**Tech Stack:** Quickshell 0.3.0, Qt 6 QML, Quickshell Io and PipeWire, Hyprland 0.56 Lua configuration, systemd, Bash integration contracts
+
+**Spec:** `docs/superpowers/specs/2026-08-17-panama-settings-design.md`
+
+## Global Constraints
+
+- Use Tokyo Night Moon tokens and the existing Prism edge; no component-local color literals.
+- Apply only allow-listed Hyprland numeric settings; never execute UI-provided shell text.
+- Do not expose full-time desktop HDR without tested automatic rollback.
+- Do not continuously poll or animate while idle.
+- Preserve GNOME Settings as an installed, searchable fallback.
+- Keep unrelated pre-existing Panama changes untouched.
+
+---
+
+### Task 1: Persisted desktop preferences
+
+**Files:**
+- Create: `config/dot/quickshell/config/DesktopPreferences.qml`
+- Modify: `config/dot/quickshell/config/Settings.qml`
+- Test: `tests/quickshell/settings-preferences-contract.sh`
+
+**Interfaces:**
+- Produces: writable `use24Hour`, `showSeconds`, `showWeekday`, `showCpu`, `showMemory`, `showGpu`, `dockAutohide`, `dockRevealDelayMs`, `dockHideDelayMs`, `focusDurationMinutes`, `autoHdr`, `vrrPolicy`, `directScanoutPolicy`, and `lastPage` properties plus `resetDesktopDefaults(): void`.
+- Consumes: `Quickshell.stateDir`, `FileView`, and `JsonAdapter`.
+
+- [x] Write a standalone Quickshell contract that changes clock, dock, and display-policy values in a disposable state directory, restarts the harness, and asserts the literal values survive.
+- [x] Run the contract and verify it fails because `DesktopPreferences` does not exist.
+- [x] Implement the JSON adapter and bind dynamic `Settings.qml` values to it.
+- [x] Run the persistence contract and the existing focus/dock consumers to green.
+
+### Task 2: Allow-listed system boundary
+
+**Files:**
+- Create: `config/dot/quickshell/services/SystemSettings.qml`
+- Test: `tests/quickshell/settings-system-contract.sh`
+
+**Interfaces:**
+- Consumes: `DesktopPreferences`, `NightLight`, `Notifs`, `Caffeine`, `hyprctl`, `systemctl`, and `pgrep`.
+- Produces: monitor identity and geometry, display-policy setters, bounded `refresh(): void`, service status, `openGnomePanel(panel: string): void`, `openApplication(id: string): void`, and an inline `lastError`.
+
+- [x] Write an IPC-backed contract that applies current policy values, refreshes the active monitor, and rejects an unsupported GNOME panel.
+- [x] Run it and verify the `settings-system` diagnostics target is absent.
+- [x] Implement fixed-command processes and strict numeric/panel allow lists.
+- [x] Run the contract and confirm the live compositor returns to its original values.
+
+### Task 3: Luminous window and core pages
+
+**Files:**
+- Create: `config/dot/quickshell/modules/settings/SettingsWindow.qml`
+- Create: `config/dot/quickshell/modules/settings/SettingsShell.qml`
+- Create: `config/dot/quickshell/modules/settings/SettingsSidebar.qml`
+- Create: `config/dot/quickshell/modules/settings/SettingsCard.qml`
+- Create: `config/dot/quickshell/modules/settings/SettingRow.qml`
+- Create: `config/dot/quickshell/modules/settings/SettingsToggle.qml`
+- Create: `config/dot/quickshell/modules/settings/HomePage.qml`
+- Create: `config/dot/quickshell/modules/settings/AppearancePage.qml`
+- Create: `config/dot/quickshell/modules/settings/DisplaysPage.qml`
+- Create: `config/dot/quickshell/modules/settings/DesktopPage.qml`
+- Create: `config/dot/quickshell/modules/settings/qmldir`
+- Test: `tests/quickshell/settings-window-contract.sh`
+
+**Interfaces:**
+- Consumes: `DesktopPreferences`, `SystemSettings`, `NightLight`, and `ShellState.settingsPage`.
+- Produces: a tiled `Panama Settings` window with Home, Appearance, Displays, and Desktop pages.
+
+- [x] Write a live contract that opens the window to each core page and verifies one `Panama Settings` toplevel remains mapped.
+- [x] Run it and verify the `settings` IPC target is absent.
+- [x] Implement the two-pane Luminous shell and reusable row/card controls.
+- [x] Implement real preference, Night Light, HDR policy, VRR, direct-scanout, clock, vitals, and dock controls.
+- [x] Run the page contract and inspect Quickshell logs for construction warnings.
+
+### Task 4: System pages and fallback handoffs
+
+**Files:**
+- Create: `config/dot/quickshell/modules/settings/SoundPage.qml`
+- Create: `config/dot/quickshell/modules/settings/NotificationsPage.qml`
+- Create: `config/dot/quickshell/modules/settings/ShortcutsPage.qml`
+- Create: `config/dot/quickshell/modules/settings/ServicesPage.qml`
+- Create: `config/dot/quickshell/modules/settings/AboutPage.qml`
+- Modify: `config/dot/quickshell/modules/settings/SettingsShell.qml`
+- Test: `tests/quickshell/settings-pages-contract.sh`
+
+**Interfaces:**
+- Consumes: existing PipeWire controls, `Notifs`, `FocusSession`, service status from Task 2, and fixed GNOME panel handoffs.
+- Produces: Sound, Notifications & Focus, Shortcuts, Startup & Services, and About destinations.
+
+- [x] Extend the page contract with search routing, live DND/focus changes, audio construction, service refresh, and GNOME fallback command validation.
+- [x] Run it and verify the new page names fail before implementation.
+- [x] Build the five pages using the same row/card vocabulary and no inactive fake controls.
+- [x] Run contracts and verify absent optional services render as unavailable.
+
+### Task 5: Shell, keybinding, launcher, and compositor integration
+
+**Files:**
+- Modify: `config/dot/quickshell/services/ShellState.qml`
+- Modify: `config/dot/quickshell/shell.qml`
+- Modify: `config/dot/hypr/keybinds.lua`
+- Modify: `config/dot/hypr/rules.lua`
+- Create: `config/local/share/applications/panama-settings.desktop`
+- Modify: `setup/scripts/link-dotfiles`
+- Modify: `README.md`
+- Modify: `config/dot/hypr/README.md`
+
+**Interfaces:**
+- Produces: `ShellState.settingsOpen`, `settingsPage`, typed `settings` and `settings-system` IPC targets, `Super+I`, and a searchable desktop entry.
+
+- [x] Extend the live contract to open, close, toggle, and route directly to a named page.
+- [x] Wire the Settings window and IPC handlers into the shell.
+- [x] Replace the GNOME Settings `Super+I` command with Panama IPC while retaining the GNOME desktop entry.
+- [x] Let the titled window participate in the active Hyprland tiling layout.
+- [x] Link the Panama desktop entry into `~/.local/share/applications` and refresh the launcher cache.
+
+### Task 6: Full-system verification
+
+- [x] Run every Quickshell contract, `Hyprland --verify-config`, and desktop-file validation.
+- [x] Reload Hyprland, restart Quickshell, and inspect fresh logs for errors or warnings.
+- [x] Exercise Home, Displays, Desktop, Sound, Notifications, Services, shortcut search, and a GNOME handoff.
+- [x] Capture Home, Displays, Desktop, and Services pages for visual review.
+- [x] Inspect the exact Panama diff and confirm unrelated pre-existing changes were preserved.

docs/superpowers/plans/2026-08-17-screen-intelligence.md

@@ -0,0 +1,105 @@
+# Screen Intelligence 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:** Add polished local OCR and code recognition to Panama's existing capture experience.
+
+**Architecture:** Capture keeps ownership of geometry and delegates Read captures to a focused `ScreenIntelligence` singleton. A deterministic helper emits JSON from local Tesseract and ZBar, while a transient Quickshell result surface owns presentation and explicit follow-up actions.
+
+**Tech Stack:** Quickshell 0.3.0, Qt 6 QML, Hyprland 0.56 Lua configuration, Bash, Tesseract 5, ZBar, grim, wl-clipboard
+
+**Spec:** `docs/superpowers/specs/2026-08-17-screen-intelligence-design.md`
+
+## Global Constraints
+
+- Recognition is local until Search, Translate, or Open is explicitly selected.
+- Reuse the existing Screen, Window, and Selection picker.
+- Use Tokyo Night Moon and Prism tokens; no component-local colors.
+- Do not add idle animation or polling.
+- Temporary screen captures must be removed when dismissed or replaced.
+- Missing recognition packages must degrade into clear guidance, not shell errors.
+
+---
+
+### Task 1: Recognition boundary
+
+**Files:**
+- Create: `config/dot/quickshell/scripts/screen-intelligence`
+- Create: `tests/quickshell/screen-intelligence-helper-contract.sh`
+- Modify: `setup/packages/hyprland-packages`
+
+**Interfaces:**
+- Produces: `screen-intelligence probe` and `screen-intelligence analyze-file IMAGE`, each emitting one JSON object.
+- Consumes: `tesseract`, `zbarimg`, and `jq`.
+
+- [x] Write a contract that generates a high-contrast `PANAMA SCREEN INTELLIGENCE` fixture and expects that literal text from `analyze-file`.
+- [x] Run it and verify it fails because the helper does not exist.
+- [x] Implement strict argument validation, readiness probing, OCR, code recognition, JSON encoding, and user-safe errors.
+- [x] Add `tesseract`, `tesseract-langpack-eng`, and `zbar` to the Hyprland package set.
+- [x] Run the helper contract to green with the real engine.
+
+### Task 2: Recognition state and actions
+
+**Files:**
+- Create: `config/dot/quickshell/services/ScreenIntelligence.qml`
+- Test: `tests/quickshell/screen-intelligence-contract.sh`
+
+**Interfaces:**
+- Produces: readiness properties, `phase`, `text`, detected-code data, `analyzeRegion`, `analyzeFile`, copy/search/translate/open actions, and `close`.
+- Consumes: the Task 1 helper, `grim`, `wl-copy`, `xdg-open`, and `Quickshell.cachePath`.
+
+- [x] Write a live IPC contract that expects the target, readiness JSON, fixture analysis, and cleanup.
+- [x] Run it and verify the IPC target is missing.
+- [x] Implement bounded process state, JSON parsing, explicit network actions, and temporary-file cleanup.
+- [x] Wire a typed diagnostics and command IPC target in `shell.qml`.
+- [x] Run the live contract to green.
+
+### Task 3: Capture integration and result sheet
+
+**Files:**
+- Modify: `config/dot/quickshell/services/Capture.qml`
+- Modify: `config/dot/quickshell/modules/capture/CaptureBar.qml`
+- Create: `config/dot/quickshell/modules/capture/IntelligenceResult.qml`
+- Modify: `config/dot/quickshell/shell.qml`
+
+**Interfaces:**
+- Produces: Screenshot, Record, and Read action selection plus the transient result overlay.
+- Consumes: Task 2's `analyzeRegion` and state/action API.
+
+- [x] Extend the live contract to open Selection + Read mode and inspect the exposed mode state.
+- [x] Run it and verify the Read state is absent.
+- [x] Add mutually exclusive action selection and defer recognition until the picker unmaps.
+- [x] Build processing, success, empty, code, and unavailable result states with keyboard dismissal.
+- [x] Restart Quickshell and inspect fresh logs for construction errors or warnings.
+
+### Task 4: Settings, shortcut, launcher, and documentation
+
+**Files:**
+- Create: `config/dot/quickshell/modules/settings/ScreenIntelligencePage.qml`
+- Modify: `config/dot/quickshell/modules/settings/SettingsSidebar.qml`
+- Modify: `config/dot/quickshell/modules/settings/SettingsShell.qml`
+- Modify: `config/dot/quickshell/modules/settings/qmldir`
+- Modify: `config/dot/quickshell/services/ShellState.qml`
+- Modify: `config/dot/hypr/keybinds.lua`
+- Modify: `config/dot/hypr/rules.lua`
+- Create: `config/local/share/applications/panama-screen-intelligence.desktop`
+- Modify: `config/dot/hypr/README.md`
+- Modify: `README.md`
+- Modify: `tests/quickshell/settings-pages-contract.sh`
+
+**Interfaces:**
+- Produces: Settings destination `screen-intelligence`, `Super+Shift+S`, and a searchable desktop entry.
+
+- [x] Extend Settings and keybinding contracts with the new page and shortcut.
+- [x] Run them and verify the route and bind fail.
+- [x] Build the readiness/privacy page and add it to Settings navigation.
+- [x] Add the keybinding, overlay privacy rule, desktop entry, and documentation.
+- [x] Link and validate the desktop entry, reload Hyprland, and run contracts to green.
+
+### Task 5: Full-system verification
+
+- [x] Run the helper and live Screen Intelligence contracts.
+- [x] Run every Quickshell contract and `Hyprland --verify-config`.
+- [x] Restart the live shell and inspect fresh logs.
+- [ ] Exercise a real screen-region OCR capture and confirm Copy reaches clipboard history.
+- [ ] Review the complete diff, commit the Panama snapshot, and push `main` to `origin`.