# 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:**
- [x] Enumerate vicinae's built-in commands (file search, calculator, quicklinks, snippets) from the running launcher and upstream docs for 0.26.x
- [x] Verify the calculator resolves units and currency once `qalculate` is installed; note whether currency needs network setup
- [x] 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
- [x] Check whether built-in quicklinks cover argument URL templates; if yes, Task 4 shrinks to authoring quicklinks in `config/dot/vicinae/`
- [x] Add the packages the audit proves needed; run `tests/setup/package-lists-contract`

**Findings (2026-08-21):**
- No new packages. The vicinae binary links `libqalculate.so.23` directly, so the calculator works without the `qalc` CLI; `fd-find` is unnecessary because the built-in index is good (below). The plan's guess of `qalculate` + `fd-find` in the package lists is withdrawn.
- File search passes outright: `vicinae fs query` answers in under 100ms, covers all of `~` including hidden and XDG dirs. `search_files_in_root: false` is a documented deliberate choice in vicinae.json (root search stays fast; files live behind their own command) and stays. Task 7 is a no-op.
- Quicklinks exist as vicinae's built-in "shortcuts" (`~/.local/share/vicinae/shortcuts/shortcuts.json`, currently empty), created in-launcher. They are per-user runtime data, not tracked config, so Panama ships none and Task 4 shrinks to the color picker.
- Snippets exist the same way (empty store) and overlap espanso; no work.
- `vicinae dmenu` renders a pick-list from stdin with search, section titles, and index/data output. Verified live. This replaces the planned compiled extension: Tasks 5, 6, and 8 become bash helpers piping into `vicinae dmenu`, which is simpler to build, test, and read than a TypeScript extension. `panama-search` stays the only compiled extension.
- Currency conversion is the one unchecked box a human should spot-check in the launcher once (libqalculate fetches exchange rates on demand); nothing to install either way.

### 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:**
- [x] `lock-screen`: `loginctl lock-session` (hypridle owns the Lock signal)
- [x] `suspend-system`: `systemctl suspend`
- [x] `log-out`: end the uwsm session the way the session expects (`uwsm stop`), not a bare `hyprctl dispatch exit`
- [x] `reboot-system` / `power-off`: `systemctl reboot` / `systemctl poweroff`; keywords carry the words a switcher will type ("restart", "shutdown", "sign out")
- [x] 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:**
- [x] `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
- [x] `panama-remind list` / `cancel <id>`: wrap `systemctl --user list-timers 'panama-remind-*'`
- [x] Script command with two argument slots; list/cancel as a second command
- [x] 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:**
- [x] `pick-color`: `hyprpicker -a` (autocopy), then `notify-send` the hex; degrade with a message if hyprpicker is missing
- [x] 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
- [x] Extend the launcher contract to cover both

### Task 5: Windows and processes — built as `panama-pick` + `vicinae dmenu` per Task 1's findings

The list-picking half. One bash helper, not a compiled extension: `vicinae dmenu` renders the list.

**Files:**
- Create: `config/dot/quickshell/scripts/panama-pick`
- Create: `config/local/share/vicinae/scripts/{switch-window,force-quit-window,kill-process}`
- Create: `tests/setup/launcher-commands-contract`

**Steps:**
- [x] "Switch Windows": list `hyprctl clients -j` (title, class, workspace), fuzzy filter, `hyprctl dispatch focuswindow address:` on select
- [x] "Force Quit Window" action on the same list: `hyprctl dispatch killactive` equivalent by address, SIGKILL the pid as the destructive secondary action
- [x] "Kill Process": list by name/CPU from `ps`, SIGTERM on select, SIGKILL as secondary; own process and the shell filtered out
- [x] 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/dot/quickshell/scripts/panama-pick` (ssh, recent subcommands)
- Create: `config/local/share/vicinae/scripts/{ssh-hosts,recent-files}`

**Steps:**
- [x] "SSH Hosts": parse `Host` stanzas from `~/.ssh/config` (skip wildcards), open the session in the terminal the repo already names
- [x] "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
- [x] Extend the extension contract for both commands

### Task 7: File search — resolved by Task 1: the built-in passes; no work

**Files:**
- Modify: `config/local/share/vicinae/extensions/panama-desktop/` (src/files.tsx), or vicinae config only

**Steps:**
- [x] If the built-in passed the audit: configure its roots and stop; record that in Findings
- [x] If not: `fd`-backed list command over `~`, hidden dirs excluded, bounded result count, debounced queries
- [x] 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/desktop-packages` (add `rbw`)
- Modify: `config/dot/quickshell/scripts/panama-pick` (password subcommand)
- Create: `config/local/share/vicinae/scripts/copy-password`
- Modify: `tests/setup/launcher-commands-contract` (password section)

**Steps:**
- [x] `rbw` added to a package list; first-run setup documented (`rbw config set email`, `rbw login`) and surfaced as a friendly message when unconfigured
- [x] List entries from `rbw list`; copy password on select via `rbw get` piped to `wl-copy`, never argv, never a temp file
- [x] 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)
- [x] 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
- [x] 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:**
- [x] README's Vicinae row reflects the new command families
- [x] Every new file carries the why-comment the repo expects; no `.sh` extensions anywhere
- [x] Full `panama test` run is green; README count matches

**Task 8 findings (2026-08-21):** `wl-copy --sensitive` (wl-clipboard 2.2) offers the password-manager hint MIME, and vicinae's clipboard docs commit to ignoring it — verified live against the real history database (a plain probe was recorded, a sensitive one was not) before the command was written. The clipboard clear is a 30s transient timer. Review pass caught and fixed a silent empty copy on a locked vault and a flag-shaped entry name.