Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

quickshell/nuguland/.system/specs/NL-SPEC-A7K4QX2M-nuguland-agent-onboarding/index.md

Raw
Rendered preview

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

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, bar.qml, 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. 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 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, 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.