docs: spec for flameshot screenshot tool swap

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-05-02-flameshot-screenshot-design.md

@@ -0,0 +1,118 @@
+# Switch Screenshot Stack to Flameshot
+
+**Date:** 2026-05-02
+**Status:** Approved
+
+## Summary
+
+Replace the bespoke screenshot pipeline (`scripts/screenshot.sh` + grim/slurp/wofi/notification flow) with Flameshot. Flameshot provides region select, on-canvas annotation, save, copy, and discard in a single integrated GUI — collapsing the current two-step "capture → notification → wofi → tool" flow into one.
+
+## Current Behaviour
+
+`Mod+Print` runs `~/.local/bin/screenshot` which is a symlink to `scripts/screenshot.sh`:
+
+1. `slurp | grim` for region select + capture, save to `~/Pictures/screenshot-<unix-ts>.png`.
+2. `wl-copy` the file.
+3. mako notification with thumbnail + "Actions" button (10 s timeout).
+4. If "Actions" clicked, wofi menu offers: Annotate (swappy), Annotate (satty), Open in imv, Copy path, Delete.
+
+Three keypresses or clicks to reach the annotator. The notification window steals focus for 10 seconds. Two annotators offered; both must be installed.
+
+## Target Behaviour
+
+`Mod+Print` runs `flameshot gui`. The Flameshot toolbar appears overlaid on the screen with region selector + drawing tools (arrow, rectangle, blur, text, etc.) + Save/Copy/Discard buttons. Capture, edit, and dispatch are one continuous interaction. No notification, no wofi menu, no separate annotator.
+
+## Implementation
+
+### Packages
+
+- **Add to `packages.txt`:** `flameshot` (extra repo, no AUR helper needed).
+- **Remove from `packages.txt`:** none — `swappy`, `satty`, `grim`, `slurp` are kept (used by other tools or potentially useful standalone). Flameshot replaces only the orchestration script.
+
+### Files to delete
+
+- `scripts/screenshot.sh`
+- `~/.local/bin/screenshot` (the symlink)
+- `install.sh` line: `ln -sf "$(pwd)/scripts/screenshot.sh" ~/.local/bin/screenshot`
+
+### Niri keybind change
+
+In `niri/config.kdl`, replace:
+
+```kdl
+Mod+Print { spawn "screenshot"; }
+```
+
+with:
+
+```kdl
+Mod+Print { spawn "flameshot" "gui"; }
+```
+
+Single keybind only — no additional shortcuts for full-screen / delayed / monitor modes. Those live inside the Flameshot toolbar already.
+
+### Flameshot configuration
+
+The flameshot config is **generated by `install.sh`**, not tracked in the repo. The pattern mirrors how `mako/config` is handled today — Flameshot writes machine-local state back to the file at runtime (savePath, last folder, etc.), so committing the file would create churn or risk leaking user paths into the repo.
+
+The generated file content:
+
+```ini
+[General]
+disabledTrayIcon=true
+showStartupLaunchMessage=false
+showHelp=false
+copyAndCloseAfterUpload=true
+uiColor=#81a2be
+contrastUiColor=#1d1f21
+contrastOpacity=190
+```
+
+- `disabledTrayIcon=true` — no SNI icon (the user has no system tray on the bar).
+- `showStartupLaunchMessage=false` — suppress first-run notification.
+- `showHelp=false` — suppress on-canvas tooltip overlay every capture.
+- `copyAndCloseAfterUpload=true` — auto-copy to clipboard when saved.
+- `uiColor` / `contrastUiColor` — Tomorrow Night palette (`@tn-blue` and `@tn-bg` from `theme/colors.css`) so the toolbar matches the rest of the desktop.
+- `contrastOpacity=190` — Flameshot's standard mid-opacity backdrop dimming during capture.
+
+Notably **NOT** included:
+
+- `savePath` — Flameshot's INI format does not expand `~`, so a hardcoded `/home/alex/Pictures` would break for any other user. On first save Flameshot will prompt for a destination; the user picks `~/Pictures` and Flameshot remembers it locally (the resulting file gets written through the symlink back into the repo, but `flameshot/flameshot.ini` is gitignored — see below — so it stays local).
+
+### `install.sh` changes
+
+- **Remove:** `ln -sf "$(pwd)/scripts/screenshot.sh" ~/.local/bin/screenshot`
+- **Add:** A here-doc generator block (mirroring the mako pattern, lines 32-42) that writes `~/.config/flameshot/flameshot.ini` if the file doesn't already exist:
+
+  ```bash
+  mkdir -p ~/.config/flameshot
+  if [ ! -f ~/.config/flameshot/flameshot.ini ]; then
+      cat > ~/.config/flameshot/flameshot.ini <<'INI'
+  [General]
+  disabledTrayIcon=true
+  showStartupLaunchMessage=false
+  showHelp=false
+  copyAndCloseAfterUpload=true
+  uiColor=#81a2be
+  contrastUiColor=#1d1f21
+  contrastOpacity=190
+  INI
+  fi
+  ```
+
+  The `if [ ! -f ]` guard prevents clobbering the user's saved preferences (savePath, last folder, etc.) on re-runs. This differs from the mako block (which always overwrites) — Flameshot's config accumulates user-chosen state, so we must not stomp it.
+
+## Files Touched
+
+- `packages.txt` — add `flameshot`
+- `niri/config.kdl` — change one keybind line
+- `install.sh` — remove one symlink line, add the flameshot config generator
+- `scripts/screenshot.sh` — deleted
+
+## Out of Scope
+
+- Additional keybinds (full-screen, delayed, monitor) — Flameshot's toolbar already exposes these. One keybind is enough.
+- Removing `swappy` / `satty` / `imv` / `grim` / `slurp` from packages — they're useful standalone and don't carry weight.
+- Theming Flameshot beyond the two color values — Flameshot's UI is otherwise Qt-default and doesn't take much further customization.
+- Setting `savePath` declaratively — the INI format does not support `~` expansion; let Flameshot's first-save prompt handle it.
+- Adapting to portal limitations on Wayland — if Flameshot misbehaves under the `xdg-desktop-portal-wlr` backend, that's a Flameshot/portal issue to file upstream, not something this spec addresses.