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

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

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:

• 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: 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:

• "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/dot/quickshell/scripts/panama-pick (ssh, recent subcommands)
• Create: config/local/share/vicinae/scripts/{ssh-hosts,recent-files}

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 — 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:

• 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