--- id: NL-SPEC-A7K4QX2M type: spec title: Nuguland agent onboarding architecture --- # Nuguland agent onboarding architecture An agent adds an ordinary feature from public contracts, without reading host internals first. Needing host internals is a contract gap: record it, never hide it in onboarding metrics. Ownership and QML invariants: [SYSTEM](../../SYSTEM.md). Commands, isolation, gates and evidence: [RULES](../../RULES.md). Entry fields, sizing, retention and lifecycle: [FeatureEntry.qml](../../../FeatureEntry.qml). ## Composition - One typed entry in [Registry.qml](../../../Registry.qml), plus feature-local files. Registry creates services at startup; explicit typed IPC remains in `shell.qml`. - Only registered popup names open; every other name is ignored. - `kind: "popup"`: SurfaceManager + PopupHost. `kind: "overlay"`: OverlayHost. `kind: "toggle"`: Bar activation, no panel or popup. Any kind may declare a focus overlay. - Notification toast rendering lives in `features/notifications/NotificationToasts.qml`; shell only composes its primary-output surface. - Lock and privilege are external specialized controllers, not registry kinds. - Host inputs are nullable typed Registry properties, composed in `shell.qml` and forwarded to services. Panels and hosts use typed required injection; no service locator or hidden singleton dependencies. - Optional typed entry `configuration` declarations render setup/preferences in Config; operational controls remain feature-local. Feature-local `*Config.qml` declarations share their entry's shell lifetime; services own drafts/validation/execution, Config owns presentation and section scroll/focus. Config's explicit orientation store is not a generic feature-persistence engine. - Bar reads entry presentation, never feature names. Geometry data belongs to entries, generic computation to hosts. - In-process consumers bind readonly service properties: typed scalars, `var` only for row lists and records. JSON stays at IPC/diagnostics and file/subprocess/protocol boundaries, never an internal service snapshot API. ## Files Names follow the feature's types, not mandatory `Service.qml`/`Model.js` filenames. Tests live beside sources, not in a required `tests/` directory. ```text features// .qml · Panel.qml · .js *.test.js | *.test.mjs fixtures/load.qml fixtures/suite.mjs fixtures/services/.qml # native/system integration doubles fixtures/production.mjs # optional isolated native proof ``` - Load fixture imports shell root as `import "../../.." as N`. All native/system integrations need pure doubles validated by `assertPureService`; pure production services such as OSD need none. - Suites are discovered by directory. Test APIs: [bar.mjs](../../../test-fixtures/ui/bar.mjs), [bar.qml](../../../test-fixtures/ui/bar.qml), [ui-test.mjs](../../../ui-test.mjs). - Entry `opening`/`dismissed` handlers own feature open/close work, not disposable panels, Bar or IPC. `opening` precedes popup activation and can precede panel creation; never dereference its Loader there. It fires on open, switch and repeated open; prior dismissal precedes switching. - Declare panel `sessionState`, `closeRequested` and `initialFocus` only as needed, following FeatureEntry. Preserve ordinary drafts/selection/scroll through disposal; security state keeps its explicit lifetime. - Keep literal entry layout compatible with `registryEntries()` in [sources.js](../../../test-fixtures/sources.js). This source-discovery constraint is not permission for runtime JSON registration. ## Onboard 1. Read this contract, SYSTEM, RULES, relevant feature spec and FeatureEntry. Use [audio](../../../features/audio/) as a reference, not host internals as a prerequisite. 2. Name primary action, observable result, state/geometry owners and service boundary. Cover normal, empty, unavailable, disabled, pending, failure and long-content states. 3. Implement pure logic and tests, one complete pointer/keyboard interaction, entry and fixtures. Reuse shared controls/theme; loaders for costly/rare surfaces, retention only where lifetime requires it. Prefer events to polling; snapshot unstable native collections where required; never use `childrenRect` as a general sizing shortcut. 4. Run formatting, lint (unit/Rust/load gates included), named nested suite, full UI gate. Inspect complete logs and rendered screenshots, separately reporting static/load/interaction/visual proof. Static contract guards: `typed-state.test.mjs`, `keybind-ipc.test.mjs`, `surface-geometry.test.mjs`. Shared lifecycle interaction selection: `just ui-test popups`; public open route: `openRegisteredPopup`. These checks complement, never replace, load/input/pixel proof. ## Acceptance and history Completed rollout: [plan](../../plans/NL-PLAN-C4V7TQ2X-nuguland-agent-revamp/index.md), including typed internal APIs. Recorded evidence: independent OSD onboarding with disclosed gaps; uptime two-file wiring; owner continuation judgement; green integration gates. These records establish the architecture-phase exit, not every feature's live/hardware acceptance. Phase transitions remain human decisions. No runtime activation, plugin marketplace, capability facade, distribution framework or weakened isolation/proof.