flowchart LR
  p1["1 prerequisites · recursive discovery"] --> p2["2 audio + OSD pilot · registry live"]
  p2 --> p3{"3 independent onboarding"}
  p3 -->|owner: continue| p4["4 broader migration"]
  p3 -->|owner: stop| stop["revert convention"]
  p4 --> p5["5 typed state APIs"]
  p2 --> p6["6 load-test target"]
  p4 --> p6

---
id: NL-PLAN-C4V7TQ2X
type: plan
title: Nuguland agent revamp rollout
spec: NL-SPEC-A7K4QX2M
status: draft
---

# Nuguland agent revamp rollout

```mermaid
flowchart LR
  p1["1 prerequisites · recursive discovery"] --> p2["2 audio + OSD pilot · registry live"]
  p2 --> p3{"3 independent onboarding"}
  p3 -->|owner: continue| p4["4 broader migration"]
  p3 -->|owner: stop| stop["revert convention"]
  p4 --> p5["5 typed state APIs"]
  p2 --> p6["6 load-test target"]
  p4 --> p6
```

Baseline metrics are recorded before phase 1 starts: central files touched by one audio change, context files required, registration points, iterations to green.

1. **Prerequisites**
   Fold agent law into `.system/`, remove the folded sources, extend justfile QML and test discovery to recurse into `features/` without weakening any gate.
   Exit when zero-warning lint and the full suite pass with recursive discovery.
2. **Audio + OSD pilot**
   Move audio and OSD sources, tests, and fixtures into `features/`. Introduce the typed QML registry covering their wiring. Move per-feature sizing data out of `SurfaceManager` into entries; keep generic computation. Registry-driven instantiation replaces the audio popup case and inline component in `PopoutHost`. State APIs stay JSON.
   Exit when every existing gate stays green: lint, full JS suite, `just ui-test` audio and OSD flows.
3. **Independent onboarding proof**
   Freeze the registry contract and the audio feature as reference. A second agent onboards OSD using public contracts only: `.system/`, registry, audio reference. Record central-file edits, required context files, contract gaps, and iterations.
   Exit when the owner reviews the evidence and decides continue, adjust, or stop.
4. **Broader migration**
   Migrate remaining features onto the registry one slice at a time, each with its named fixture. Decompose `SurfaceManager` and `PopoutHost` further only where migration proves the need. Specialized surfaces register their controller kind without adopting the popup lifecycle.
   Exit when each migrated feature passes its named fixture and the full gate.
5. **Typed internal service APIs**
   Separate follow-up: replace internal `stateJson()` consumption with typed readonly properties or QML models where practical; rewrite affected fixture doubles; keep JSON at IPC and diagnostics boundaries. The "where practical" criterion is defined in that follow-up.
   Exit when affected panels and fixtures pass unchanged interaction and visual evidence.
6. **Feature-local test commands**
   `just test <stem>` and `just ui-test <fixture>` already exist and stay canonical. Add the named `load-test` target for the load evidence level. No second test system.
   Exit when `just load-test <feature>` runs the isolated load check for every registry entry.