---
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.
- Popouts 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 and capture actions report success or failure without changing underlying action semantics.
- Destructive session actions require confirmation.
- Lock and suspend preserve safe ordering and the session lock boundary.

## Interface constraints

- Public IPC is stable at the behavior level.
- Existing state JSON contracts evolve additively.
- 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.

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