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.
Commands, isolation, gates and evidence: RULES.
Entry fields, sizing, retention and lifecycle: FeatureEntry.qml.
Composition
One typed entry in 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.
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.
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.
This source-discovery constraint is not permission for runtime JSON registration.
Onboard
Read this contract, SYSTEM, RULES, relevant feature spec and FeatureEntry.
Use audio as a reference, not host internals as a prerequisite.
Name primary action, observable result, state/geometry owners and service boundary.
Cover normal, empty, unavailable, disabled, pending, failure and long-content states.
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.
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, 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.
---
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/<name>/
<Type>.qml · <Type>Panel.qml · <model>.js
*.test.js | *.test.mjs
fixtures/load.qml
fixtures/suite.mjs
fixtures/services/<Type>.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.