# Upstream inspiration

Panama is its own desktop experience, but it should learn from strong open-source work without obscuring where an idea came from. This ledger records upstream projects that materially influence its architecture or interaction design.

## Omarchy

- Project: [basecamp/omarchy](https://github.com/basecamp/omarchy)
- Reviewed revision: `f32ebbdb730c4e8fe11e4046cef4267e466264ea`
- License: MIT, copyright David Heinemeier Hansson
- Local reference at review time: `/home/gib/Documents/Code/Projects/omarchy`

### Adopted ideas, rebuilt for Panama

- `shell/plugins/osd/Osd.qml` and `OsdModel.js`: inspired the separation between a pure presentation model and a single, click-through per-monitor OSD surface. Panama rebuilt the behavior around freedesktop symbolic icons, Tokyo Night Moon tokens, its Prism glass material, Hyprland's focused monitor, and the existing `wpctl`/`brightnessctl`/`playerctl` keybindings.
- `test/shell.d/osd-test.sh` and Omarchy's broader shell contract suite: reinforced Panama's use of fast model and integration contracts alongside live compositor verification.
- Omarchy's small shared visual primitives: reinforced the decision to maintain `prism-gallery.qml`, which renders Panama's production widgets and Theme tokens instead of duplicating mock-only controls.
- `shell/plugins/menu/Menu.qml`: inspired a searchable desktop-action inventory. Panama keeps Vicinae as its one launcher and exposes native script commands backed by a single `panama-action` dispatcher, rather than adding Omarchy's separate shell menu or plugin host.

No Omarchy user-facing layout or styling was transplanted. Panama keeps its GNOME-derived information architecture, Prism material, Tokyo Night Moon palette, app model, and established interaction choices.

### Second round, 2026-08-22

A survey of omarchy, end-4/dots-hyprland, caelestia, DankMaterialShell,
noctalia, HyDE, ML4W, JaKooLit and hyprdots, read against Panama's own feature
inventory. This is the largest borrowing round the project has had, and what
follows is what was taken, what was rebuilt rather than transplanted, and what
was declined.

**Omarchy** ([basecamp/omarchy](https://github.com/basecamp/omarchy), MIT,
reviewed at `f32ebbdb`).

- `bin/omarchy-migrate` and `migrations/`: the idea that an installed machine
  needs a way to catch up, because installing only ever adds. Panama rebuilt it
  as `bin/panama-migrate` with the same shape -- commit-timestamp filenames so
  glob order is chronological, one marker file per migration written only on
  success -- and the same reasoning appears in the existing
  `config/Migrations.qml`, which already did this for the settings file.
  Panama's runner stops at the first failure rather than continuing, and root
  work goes through `panama-sudo` so the password prompt names the repair.
- `bin/omarchy-launch-or-focus`: focusing a window rather than opening a second
  one. Panama inverted the default after using it: the plain application keys
  keep opening a new window, and `SUPER+ALT` is the go-to chord. On a tiling
  desktop a second terminal beside the first is the normal case, not an edge
  one, and making that the awkward path was a worse trade than the parity.
- `bin/omarchy-webapp-install`: a site as an application. Rebuilt as
  `bin/panama-webapp`, following the desktop's own default browser rather than
  naming one, and refusing a browser that cannot do app mode instead of opening
  an ordinary window and pretending.
- `bin/omarchy-hw-*`: small exit-code hardware predicates. Rebuilt as one
  `bin/panama-hw` with subcommands, including reading sysfs vendor IDs rather
  than `lspci`, which wakes a runtime-suspended GPU.
- `bin/omarchy-hyprland-monitor-clamshell`: the definition that clamshell is a
  closed lid *and* an external monitor. Panama took the definition and rejected
  the mechanism: rather than a logind drop-in plus a watcher of its own, it
  holds a `handle-lid-switch` inhibitor, so a failure returns logind's default
  instead of leaving a lid that does nothing.
- `manual/`: user documentation as numbered prose chapters, and specifically a
  "coming from Mac or Windows" chapter. Panama's `config/dot/quickshell/manual/`
  renders inside Settings rather than opening a browser.
- Nautilus context-menu extensions: rebuilt against Panama's existing
  `panama-kdeconnect` rather than adding a second way to talk to a phone.

**end-4/dots-hyprland** ([repo](https://github.com/end-4/dots-hyprland)) and
**omarchy**: a keybind cheatsheet on one keypress, read from the live keymap
rather than a written-down copy. Panama's version groups by categories the
compositor config declares, written to a manifest at config load, because
Hyprland reports Lua binds as `__lua` with a bytecode offset and nothing can
ride along into `hyprctl binds`.

**ML4W** ([dotfiles-welcome](https://github.com/mylinuxforwork/dotfiles-welcome)):
a first-run welcome that teaches the handful of keys that matter and stays
reachable afterwards. Panama's reads the chords from the live keymap so it
cannot teach keys the machine does not have.

**HyDE** ([wallbash templates](https://github.com/HyDE-Project/HyDE)) and
omarchy's `default/themed/`: color values as data consumed by templates rather
than restated per consumer. Panama took the principle and not the template
engine: `config/palette.json` is now the single source for everything outside
QML, which removed six hand-synced copies of the eight accents. A per-app
template renderer was considered and deferred, because the concrete pain it
would solve is gone and porting six working generators is risk without a
waiting beneficiary.

**caelestia** ([caelestia-dots/shell](https://github.com/caelestia-dots/shell)):
lightweight system toasts as a category distinct from the OSD and the
notification center. Panama already had this as `StatusEvents`, so what was
taken was the observation that a charger belongs in it; the layer itself needed
no work.

**DankMaterialShell** ([repo](https://github.com/AvengeMedia/DankMaterialShell)):
surfacing agent usage in the bar, and a plugin registry with a lockfile. The
first shipped, as a bar widget with a switch of its own on Shell › Bar; the
second remains deferred, see below.

**Omarchy** ([repo](https://github.com/basecamp/omarchy), MIT — DHH): the
crash-to-agent escalation ladder and the multi-agent usage collectors, both
taken as code, not just ideas, with attribution headers on every derived file.
Specifically: the command-as-notification-data hint (the shell runs the click,
so it survives shell restarts and never blocks the sender), the per-agent argv
launch table with the skill-path-as-fallback trick for harnesses without a
skill mechanism, the coredump PID+signal payload, and the Claude collector's
hard-won honesty — model-scoped limits, cached numbers that expire on window
rollover rather than age, waiting-vs-expired auth as distinct states, and
retry-on-transport-but-not-HTTP-error. The diagnose-crash skill's structure
("rule out OOM first", "never invent function names", "diagnosis reads; it
does not fix") was adapted rather than rewritten, because it was already
right. Their usage panel and menu system were not taken — Panama renders its
own surfaces in its own design language.

### Declined, and why

- **Wallpaper-derived dynamic color** (HyDE wallbash, matugen). The headline
  feature of this whole genre, and declined on identity: Tokyo Night Moon is a
  deliberate choice, and dynamic color is how rices end up looking like each
  other. Reconsider as one more theme profile, never as the default.
- **A per-app template engine for theming.** See above.
- **Audio visualizers.** A continuously repainting equalizer is exactly the
  GPU-pegging animation this project avoids on high-refresh displays.
- **Theming applications by patching their internals** (Spotify, Discord).
  Breaks on every application update; the maintenance is unbounded and falls on
  whoever is holding the desktop that day.
- **A plugin host.** Still premature, for the reason already recorded below.
  User hooks were the thirty-line version and shipped instead: `panama-hook`
  runs `~/.config/panama/hooks/<name>` and its `<name>.d/` directory for
  `theme-set`, `post-upgrade` and `post-migrate`.
- **Package channels and pacman hooks.** Arch-specific, and blocking
  `dnf upgrade` on a Fedora workstation would be hostile.

### Candidates still under evaluation

- A plugin boundary for optional bar widgets and services once Panama has enough third-party modules to justify one.
- A small first-run health check for missing desktop dependencies and broken service integrations.

These are research directions, not commitments. They should only land when they improve the daily-driver experience without adding visible complexity or parallel configuration systems.
