# Independent OSD onboarding ## Historical evidence Names, paths, findings and gate counts below describe the recorded tree, not today's onboarding contract. Current contract: [onboarding](../../specs/NL-SPEC-A7K4QX2M-nuguland-agent-onboarding/index.md). Step 4 evidence, 2026-11-13, for the owner's continue, adjust, or stop decision. A fresh child agent (Claude Opus, high reasoning) onboarded the OSD with only the public contracts as its brief: `.system/`, `Registry.qml`, `FeatureEntry.qml`, `features/audio/`, `justfile`, the fixture README, and the UI skill. It recorded its own reads, gate runs, and gaps; the parent agent read the diff and re-ran every gate. The work sits on branch `revamp/osd-onboarding`, not on trunk. ## Production load: unproven No gate loads production `shell.qml`; the `just lint` runtime stage only pings the already running shell. The live desktop shell hot-reloads this working tree, so it loaded the child's in-progress OSD states: its log shows `Unable to assign Osd_QMLTYPE… to Osd_QMLTYPE…` at `shell.qml` (the `Media` injection) and `Registry.qml` (the panel binding), followed by panel `TypeError`s. Those warnings may be a stale type cache from hot-reloading a moved type, or a real type-identity defect; a later reload logged no warnings, but which tree state it loaded is unknown. A fresh, isolated production load of the branch has not been run. ## Result - OSD lives in `features/osd/`: service, pure model, model test, panel, load target. - `Registry.qml` gains an `overlays` list with the OSD entry; a new generic `OverlayHost.qml` replaces the inline OSD surface in `shell.qml` and keeps its per-screen, primary-screen-only, click-through, keyboardless behavior. - Parent re-run on the branch: `just lint` 0 (includes `just test` and `just load-test`), `just load-test osd` 0, `just ui-test` 9/9 in 31 s. - The OSD card moved with identifier renames and added `objectName`s only (parent diff read against trunk `shell.qml`). - Rendering: the parent viewed two 1280×720 screenshots; 1366×768 and 2560×1440 rest on the child's review. There is no pre-move nested OSD image to compare against, and event icons render empty in the fixture. - Step 2's exit (`just load-test osd`) is met only on this branch; trunk has no OSD load target. ## Against the pilot's prediction `baseline.md` "After the audio pilot" predicted a second feature needs 2 production and 4 shared test files. | Metric | Predicted | OSD onboarding | | --- | --- | --- | | Onboarded from public contracts alone | goal | no | | Host-internal files read | 0 | about 12, each recorded with its blocker | | Production files changed outside `features/osd/` | 2 | 8: `Registry.qml`, `FeatureEntry.qml`, new `OverlayHost.qml`, `shell.qml`, `Media.qml`, `Brightness.qml`, `Screenshots.qml`, the audio reference `features/audio/Audio.qml` | | Test and harness files changed | 4 | 9: `load-test.mjs`, `ui-test.mjs`, `ui-test.test.mjs`, `tasks.mjs`, `tasks.qml`, four brightness tests | | Iterations to green | unmeasured | 11 gate runs from first edit to first full green, 6 failing; 4 more after a test race surfaced at another size | OSD is an overlay with a cross-feature service type, the hardest kind of second feature; an ordinary popup would cost less, but how much less is unmeasured. ## Contract gaps 1. `FeatureEntry.kind` and `uiSuite` are read by nothing; every entry is a popup. Workaround: a separate `overlays` list and `OverlayHost`; `kind` and list membership now duplicate each other. 2. The entry has no data for overlay visibility or placement. Workaround: `overlayShown`; placement is `OverlayHost` policy. 3. Moving a service other features type against (`Osd`) fans out to every consumer, including test copies. The contracts are silent on cross-feature service types. 4. `just load-test` applied only the target feature's doubles, but the registry creates every feature's service. The branch makes it apply every feature's doubles, which also changes `just load-test audio`; `RULES.md` still describes the old behavior. 5. A named `ui-test` suite cannot be added from feature-local files: suite name, branch, projection, and events live in four shared test files. 6. No public way for a fixture to locate overlay surfaces. Workaround: `OverlayHost.surface(name)`. 7. Undocumented: screenshot names containing `error`/`failed`/`warn` trip the log gate. 8. Undocumented: keys sent before `popup.windowActive` are lost. 9. No isolated production load of `shell.qml` exists (see above). ## Owner decision 2026-11-13: continue, adjusting the contract first (plan step 4b). Addressed in step 4b: gap 1 (hosts read `kind`), gap 5 (feature-local suites), and agent isolation from the live shell. ## Open issues - The OSD renders capitalized labels (`Volume`, `Microphone`, `Error`, `OSD`) against the lowercase-label rule; existing behavior, left unchanged. - Event icons are empty in the nested fixture because it lacks the production icon theme pragma; production icon rendering is unproven. - The frozen audio reference changed one import line. - The `osd` suite drives events through fixture IPC, not through real producers. - Agents editing this working tree hot-reload the user's live desktop shell; isolation needs a decision.