Plan the launcher's climb to OS parity

docs/superpowers/plans/2026-08-21-vicinae-os-parity.md

@@ -0,0 +1,142 @@
+# Vicinae OS-Parity 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:** Close the launcher gaps a GNOME, macOS, or Windows switcher notices in week one. The launcher is deep where Panama is deep (settings, projects, focus) and thin where a stock OS is strong: finding files, windows, and your own stuff. After this plan, Spotlight and Start-menu reflexes land somewhere.
+
+**Architecture:** Two mechanisms, chosen per feature by whether the result is a list.
+
+- *Script commands* (`config/local/share/vicinae/scripts/`, published by `link-vicinae-scripts`) for toggles and argument commands: power menu, reminders, color picker, quicklinks. Annotation-header bash, `@vicinae.mode silent` or an argument slot.
+- *One new compiled extension* (`config/local/share/vicinae/extensions/panama-desktop/`, TypeScript, built at link time like `panama-search`) for everything that presents a live list to pick from: window switcher, force quit, kill process, SSH hosts, recent files. Vicinae script commands cannot render pick-lists; `panama-search` proves the extension path.
+
+Backends are things the system already has: `hyprctl clients -j`, `systemd-run --user`, `hyprpicker`, `~/.ssh/config`, `recently-used.xbel`, `rbw`.
+
+**Tech Stack:** Bash, jq, TypeScript (Vicinae extension API), vicinae 0.26.3, hyprctl, systemd-run, rbw
+
+**Spec:** none — shaped in conversation 2026-08-21; this plan is self-contained.
+
+## Global Constraints
+
+- A command whose backend is missing must degrade to a clear message, never a stack trace. `command -v` guards, not assumptions.
+- Secrets never touch argv or files: rbw output goes straight to the clipboard, with a timed clear. The Bitwarden task lands alone, after review, never batched.
+- No new daemons and no polling. Every command does its work when invoked and exits.
+- Reuse the existing wiring: script commands exec helpers in `config/dot/quickshell/scripts/` when logic is nontrivial, the way `open-project` execs `panama-project`.
+- Every task extends or adds a contract. New test files bump the README count (`tests/setup/readme-contract` enforces it).
+- New packages go in the package lists, never inline in scripts. `tests/setup/package-lists-contract` verifies names against the repositories.
+- The terminal for SSH sessions is the one `panama-project` already names; do not add a fifth copy of the kitty literal without checking whether the terminal-ownership cleanup has landed.
+
+---
+
+### Task 1: Audit the built-ins, land the missing dependencies
+
+What vicinae 0.26.3 already ships decides whether file search and the calculator are configuration or code. Do not build before answering.
+
+**Files:**
+- Modify: `setup/packages/desktop-packages` (or `initial-packages`) — add `qalculate`, `fd-find`
+- Create: audit notes appended to this plan under Findings
+
+**Steps:**
+- [ ] Enumerate vicinae's built-in commands (file search, calculator, quicklinks, snippets) from the running launcher and upstream docs for 0.26.x
+- [ ] Verify the calculator resolves units and currency once `qalculate` is installed; note whether currency needs network setup
+- [ ] Test built-in file search against `~`: coverage, latency, whether hidden and XDG dirs are respected; record whether Task 7's file listing is needed at all
+- [ ] Check whether built-in quicklinks cover argument URL templates; if yes, Task 4 shrinks to authoring quicklinks in `config/dot/vicinae/`
+- [ ] Add the packages the audit proves needed; run `tests/setup/package-lists-contract`
+
+### Task 2: Power menu script commands
+
+**Files:**
+- Create: `config/local/share/vicinae/scripts/{lock-screen,suspend-system,log-out,reboot-system,power-off}`
+- Modify: `tests/setup/launcher-search-contract` (or sibling) to cover the new commands
+
+**Steps:**
+- [ ] `lock-screen`: `loginctl lock-session` (hypridle owns the Lock signal)
+- [ ] `suspend-system`: `systemctl suspend`
+- [ ] `log-out`: end the uwsm session the way the session expects (`uwsm stop`), not a bare `hyprctl dispatch exit`
+- [ ] `reboot-system` / `power-off`: `systemctl reboot` / `systemctl poweroff`; keywords carry the words a switcher will type ("restart", "shutdown", "sign out")
+- [ ] Contract: every power command exists, is executable, and names only binaries the package lists provide
+
+### Task 3: Reminders and timers
+
+**Files:**
+- Create: `config/local/share/vicinae/scripts/remind-me`
+- Create: `config/local/share/vicinae/scripts/list-reminders`
+- Create: `config/dot/quickshell/scripts/panama-remind`
+- Create: `tests/quickshell/remind-contract`
+
+**Steps:**
+- [ ] `panama-remind add "<when>" "<text>"`: parse `20m` / `1h` / `9:30` into `systemd-run --user --on-active=` or `--on-calendar=`, unit named `panama-remind-<id>`, firing `notify-send` with the text
+- [ ] `panama-remind list` / `cancel <id>`: wrap `systemctl --user list-timers 'panama-remind-*'`
+- [ ] Script command with two argument slots; list/cancel as a second command
+- [ ] Contract: add, list, and cancel against a stub `systemd-run`/`systemctl`; a nonsense time is refused with a message, not a unit
+
+### Task 4: Color picker and quicklinks
+
+**Files:**
+- Create: `config/local/share/vicinae/scripts/pick-color`
+- Create or configure: quicklinks per Task 1's finding
+
+**Steps:**
+- [ ] `pick-color`: `hyprpicker -a` (autocopy), then `notify-send` the hex; degrade with a message if hyprpicker is missing
+- [ ] Quicklinks: if built-in, author Panama's defaults (Gitea, Flathub, package search) in tracked config; if not, one `open-quicklink` script command with an argument
+- [ ] Extend the launcher contract to cover both
+
+### Task 5: The panama-desktop extension — windows and processes
+
+The list-picking half. One extension, several commands, built at link time exactly like `panama-search` (respect the rebuild-staleness caveat noted in link-vicinae-scripts).
+
+**Files:**
+- Create: `config/local/share/vicinae/extensions/panama-desktop/` (package.json, src/windows.tsx, src/processes.tsx)
+- Modify: `setup/scripts/link-vicinae-scripts` if the build loop assumes a single extension
+- Create: `tests/setup/vicinae-extension-contract` (or extend the existing extension coverage)
+
+**Steps:**
+- [ ] "Switch Windows": list `hyprctl clients -j` (title, class, workspace), fuzzy filter, `hyprctl dispatch focuswindow address:` on select
+- [ ] "Force Quit Window" action on the same list: `hyprctl dispatch killactive` equivalent by address, SIGKILL the pid as the destructive secondary action
+- [ ] "Kill Process": list by name/CPU from `ps`, SIGTERM on select, SIGKILL as secondary; own process and the shell filtered out
+- [ ] Contract: extension builds from a clean checkout; commands are declared in package.json; no network access in the build sandbox beyond the dependency install `panama apps` already performs
+
+### Task 6: SSH hosts and recent files
+
+**Files:**
+- Modify: `config/local/share/vicinae/extensions/panama-desktop/` (src/ssh-hosts.tsx, src/recent-files.tsx)
+
+**Steps:**
+- [ ] "SSH Hosts": parse `Host` stanzas from `~/.ssh/config` (skip wildcards), open the session in the terminal the repo already names
+- [ ] "Recent Files": parse `~/.local/share/recently-used.xbel`, newest first, open with `xdg-open`; missing file means an empty list with a hint, not an error
+- [ ] Extend the extension contract for both commands
+
+### Task 7: File search — only if Task 1 says so
+
+**Files:**
+- Modify: `config/local/share/vicinae/extensions/panama-desktop/` (src/files.tsx), or vicinae config only
+
+**Steps:**
+- [ ] If the built-in passed the audit: configure its roots and stop; record that in Findings
+- [ ] If not: `fd`-backed list command over `~`, hidden dirs excluded, bounded result count, debounced queries
+- [ ] Either way: the launcher finds a file by name from a cold start in under a second on this machine, and the contract asserts the chosen path exists end to end
+
+### Task 8: Bitwarden via rbw — alone, last, carefully
+
+**Files:**
+- Modify: `setup/packages/` (add `rbw`)
+- Modify: `config/local/share/vicinae/extensions/panama-desktop/` (src/passwords.tsx)
+- Create: `tests/setup/rbw-command-contract`
+
+**Steps:**
+- [ ] `rbw` added to a package list; first-run setup documented (`rbw config set email`, `rbw login`) and surfaced as a friendly message when unconfigured
+- [ ] List entries from `rbw list`; copy password on select via `rbw get` piped to `wl-copy`, never argv, never a temp file
+- [ ] Clipboard clears after 30 seconds (`wl-copy --clear` scheduled with `systemd-run --user --on-active=30s` or vicinae's own clipboard hygiene if it offers one — check first)
+- [ ] Contract with a stub rbw: copy path never leaks the secret into argv or the environment of anything but wl-copy; unconfigured rbw degrades to the setup message
+- [ ] Review pass on this task's diff before it merges, separate from writing it
+
+### Task 9: Documentation and closeout
+
+**Files:**
+- Modify: `README.md` (launcher section, test count)
+- Modify: `docs/settings.md` if any command grew a settings surface
+- Modify: this file — Findings section, boxes ticked
+
+**Steps:**
+- [ ] README's Vicinae row reflects the new command families
+- [ ] Every new file carries the why-comment the repo expects; no `.sh` extensions anywhere
+- [ ] Full `panama test` run is green; README count matches