--- 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.