One named Nuguland shell owns the desktop companion UI.
Compositor, session, idle, lock, clipboard-storage, and authorization primitives remain separate unless an approved replacement is safer and simpler.
Required surfaces
One bar appears on the configured primary output and represents workspaces from all relevant outputs.
The bar exposes workspace navigation, clock and calendar, media, notifications, tray, resources, audio, brightness, connectivity, clipboard, launcher, idle inhibition, and power controls.
Popups expose full interaction and dismiss predictably by outside click or Escape.
Native notifications provide urgency, actions, history, dismissal, and do-not-disturb behavior without a competing daemon.
Launcher and clipboard surfaces support keyboard navigation, selection, Escape dismissal, and empty states.
OSD reports supported user-initiated changes without altering action semantics; native niri screenshot bindings remain separate from the shell.
Destructive session actions require confirmation.
Lock and suspend preserve safe ordering and the session lock boundary.
Interface constraints
Public IPC consists of the methods called by niri/cfg/keybinds.kdl plus nuguland diagnostics, stable at the behavior level.
Test-only IPC is retained only while its isolated tests need it.
Owner-approved cleanup (2026-11-14) removes unused debug IPC, password-over-argv methods, runtime self-tests, non-functional descriptors, and unreachable screenshot APIs; functional state and diagnostics version 1 remain compatible.
External command boundaries are narrow, explicit, and inspectable.
Shared services enter components through the shell composition root, not hidden global state.
All UI labels are lowercase.
Visual constraints
Nugu semantic roles are the visual source of truth.
Active controls use focus semantics, hover uses accent semantics, muted content uses minor semantics, and failures use warning or error semantics.
IBM Plex Sans is the UI font.
IBM Plex Mono is used for fixed-width status or numeric alignment.
Components remain usable in both Nugu modes.
Migration and safety
Replacement surfaces reach functional and visual parity before incumbent frontends retire.
Notification ownership changes under a proven rollback guard and never intentionally leaves two daemons competing.
Security-sensitive agents and lock behavior remain until separately specified and approved.
Retirement removes live references and service enablement.
Package removal is separate scope.
Configuration
Config hosts setup/preferences, not operational controls, through feature-local typed registry declarations.
Noko installation, update check/update, asset/dependency readiness, progress and setup errors render in Config; capture/transcription/history stay in Noko with a deep link.
Noko rejects duplicate setup, setup during capture/transcription and capture during install.
Native installer ownership survives navigation and progress events until actual exit; a done event is not completion, and nonzero exit remains failure.
Acceptance
The shell starts through the graphical-session service without QML errors or warnings.
Every visible control passes its interaction matrix, including failure paths.
Workspace state updates without polling helpers.
Destructive actions cannot execute without confirmation.
Exactly one notification daemon owns the notification bus.
No retired frontend remains on a live configuration path.
Dark and light visual checks pass when theme switching is enabled.
The shell remains recoverable through a documented service rollback.
---
id: NL-SPEC-86A037A0
type: spec
title: Nuguland companion shell
---
# Nuguland companion shell
## Outcome
One named Nuguland shell owns the desktop companion UI.
Compositor, session, idle, lock, clipboard-storage, and authorization primitives remain separate unless an approved replacement is safer and simpler.
## Required surfaces
- One bar appears on the configured primary output and represents workspaces from all relevant outputs.
- The bar exposes workspace navigation, clock and calendar, media, notifications, tray, resources, audio, brightness, connectivity, clipboard, launcher, idle inhibition, and power controls.
- Popups expose full interaction and dismiss predictably by outside click or Escape.
- Native notifications provide urgency, actions, history, dismissal, and do-not-disturb behavior without a competing daemon.
- Launcher and clipboard surfaces support keyboard navigation, selection, Escape dismissal, and empty states.
- OSD reports supported user-initiated changes without altering action semantics; native niri screenshot bindings remain separate from the shell.
- Destructive session actions require confirmation.
- Lock and suspend preserve safe ordering and the session lock boundary.
## Interface constraints
- Public IPC consists of the methods called by `niri/cfg/keybinds.kdl` plus `nuguland diagnostics`, stable at the behavior level.
- Test-only IPC is retained only while its isolated tests need it.
- Owner-approved cleanup (2026-11-14) removes unused debug IPC, password-over-argv methods, runtime self-tests, non-functional descriptors, and unreachable screenshot APIs; functional state and diagnostics version 1 remain compatible.
- External command boundaries are narrow, explicit, and inspectable.
- Shared services enter components through the shell composition root, not hidden global state.
- All UI labels are lowercase.
## Visual constraints
- Nugu semantic roles are the visual source of truth.
- Active controls use focus semantics, hover uses accent semantics, muted content uses minor semantics, and failures use warning or error semantics.
- IBM Plex Sans is the UI font.
- IBM Plex Mono is used for fixed-width status or numeric alignment.
- Components remain usable in both Nugu modes.
## Migration and safety
- Replacement surfaces reach functional and visual parity before incumbent frontends retire.
- Notification ownership changes under a proven rollback guard and never intentionally leaves two daemons competing.
- Security-sensitive agents and lock behavior remain until separately specified and approved.
- Retirement removes live references and service enablement.
- Package removal is separate scope.
## Configuration
- Config hosts setup/preferences, not operational controls, through feature-local typed registry declarations.
- Noko installation, update check/update, asset/dependency readiness, progress and setup errors render in Config; capture/transcription/history stay in Noko with a deep link.
- Noko rejects duplicate setup, setup during capture/transcription and capture during install.
- Native installer ownership survives navigation and progress events until actual exit; a `done` event is not completion, and nonzero exit remains failure.
## Acceptance
- The shell starts through the graphical-session service without QML errors or warnings.
- Every visible control passes its interaction matrix, including failure paths.
- Workspace state updates without polling helpers.
- Destructive actions cannot execute without confirmation.
- Exactly one notification daemon owns the notification bus.
- No retired frontend remains on a live configuration path.
- Dark and light visual checks pass when theme switching is enabled.
- The shell remains recoverable through a documented service rollback.