One visual shell.
Explicit system adapters.

Lucent starts with the session.

The user Hyprland configuration prepends Lucent’s compatibility commands to PATH and starts lucent.service. The installed Omarchy startup callback still invokes omarchy-launch-shell, but its user-level adapter starts the same Lucent service. Systemd keeps one instance. Packaged files are untouched.

Hyprland login
  → user PATH / autostart
  → lucent.service → session.py → lucent-desktop
       ├─ background / bar / dock / widgets / notifications / OSD
       ├─ lucent-polkit.service → libpolkit-agent + native dialog
       ├─ lucent-idle.service → swayidle → secure lock
       └─ lucent-clipboard.service → wl-paste → private history

Permission request → polkit → lucent-polkit → SessionScreen
Lock request       → lock.py → lucent-lock → ext-session-lock
Theme selection    → ThemePort → LucentTheme → app exports

Activation stops only the current user’s installed stock shell and its restart supervisor, after checking native readiness. It refuses to interrupt a secure lock. A desktop failure restarts Lucent; it does not silently switch visual shells. Explicit rollback restores stock startup. Read the supervisor and the installer.

Rendering and behavior
have separate owners.

Audio, Wi-Fi, Bluetooth, power and tray have native panels. Enterprise networking, Wi-Fi QR and custom stock plugins remain outside their current coverage. Real tray applications and hardware-specific radios, audio, battery, brightness, sleep and display behavior still need acceptance. The live-wallpaper VM report establishes single-output import, changing native pixels, pause/resume, input and restart on its recorded source; the historical image-lifetime samples retain their original workload and source. The Display-binary 120-second software-Vulkan video sample records 384.82 MiB mean and 403.88 MiB peak RSS, above the 300 MiB target. The earlier Weather cohort retains its 424.12/424.15 MiB result. These different workloads are not a matched comparison. Multi-output, physical-GPU efficiency and actual presentation pacing remain open. The readiness guide separates accepted native fixtures from real application and hardware coverage.

The direction is outward.

design/tokens.json
  ├─ primitive palette / spacing / type / motion
  └─ semantic roles → component recipes
       ├─ generated Rust → Lucent clients
       ├─ generated CSS → documentation/design system
       ├─ window rules → Hyprland
       └─ selected semantic palette → application configuration
            ├─ Omarchy templates (headless, background preserved)
            ├─ GTK named colors + desktop color-scheme
            ├─ Foot / tmux colors and browser toolbar policy
            └─ login palette + emergency lock configuration

Choose a named palette or extract colors from a wallpaper. The component updates its semantic roles, schedules persistence of the complete palette on the settings queue and invokes ThemePort on the separate ordered theme queue. LucentTheme runs the export adapter. The standard Omarchy theme picker is replaced, and arbitrary stock theme names are rejected while the integration is active. Light/dark is only an application compatibility hint derived from the palette’s surface luminance.

The exporter calls the installed template generator with OMARCHY_THEME_HEADLESS=1 and OMARCHY_THEME_SKIP_BACKGROUND=1. It does not run theme hooks or a reverse synchronization loop. Application support differs: GTK applications may override named colors; browsers may need a reload/restart for managed toolbar colors; websites and app-specific themes remain their own content.

Exports have a first-run backup and managed CSS blocks. Failures appear as theme_error in inspection and in the theme panel. The native palette can change before an external application finishes applying its export. See the token reference and the export adapter.

Compatibility is an adapter.

The menu bridge reads installed JSONC definitions and user extensions. The reusable Rust picker accepts entries, labels and opaque values; it does not execute commands. Python integration adapters discover system state and validate the exact selected value before invoking an argument array. Trusted user menu actions may still be shell expressions.

lucent-compat.py translates known stock IPC names to native actions. For example, omarchy-shell shell toggle omarchy.audio toggles the native desktop audio panel, and notification dismissal targets Lucent’s notification port. Unknown operations return an error. User extensions can intentionally launch other applications and remain user-owned.

These Python scripts are distribution compatibility adapters, not framework APIs. The domain has typed ports for capabilities used by Rust components; the generic framework has no knowledge of Omarchy names, palette export files or system commands. Read the ports and adapters guide.

Inspect the running owners.

systemctl --user status lucent.service lucent-polkit.service lucent-idle.service lucent-clipboard.service
lucent-cli inspect
hyprctl -j layers

# Explicit return to the original desktop integration
python3 scripts/lucent-setup.py rollback

Rollback removes only managed blocks, restores the application theme backup, stops native desktop services and starts the installed stock shell. Native binaries and saved preferences remain. Login-manager rollback is separate. Review startup and command contracts after distribution updates; keep local process dumps, credentials and private screenshots out of Git.