GeneralD
diff --git a/‎.claude/rules/architecture-boundaries.md‎
Lines changed: 23 additions & 0 deletions b/‎.claude/rules/architecture-boundaries.md‎
Lines changed: 23 additions & 0 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 41 additions & 2 deletions b/‎AGENTS.md‎
Lines changed: 41 additions & 2 deletions
diff --git a/‎Package.swift‎
Lines changed: 45 additions & 0 deletions b/‎Package.swift‎
Lines changed: 45 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 10 additions & 0 deletions b/‎README.md‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎Sources/AppRouter/AppDependencyBootstrap.swift‎
Lines changed: 1 addition & 0 deletions b/‎Sources/AppRouter/AppDependencyBootstrap.swift‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎Sources/AppRouter/AppRouter.swift‎
Lines changed: 58 additions & 24 deletions b/‎Sources/AppRouter/AppRouter.swift‎
Lines changed: 58 additions & 24 deletions
diff --git a/‎Sources/AppRouter/OverlayWindow.swift‎
Lines changed: 1 addition & 0 deletions b/‎Sources/AppRouter/OverlayWindow.swift‎
Lines changed: 1 addition & 0 deletions
@@ -11,6 +11,29 @@
 | **CLI Command** | Argument parsing, thin glue | Loops, task groups, complex branching |
 | **DataStore** | Persistence/cache of *domain data* — Entity values a Repository reads back (SQLite caches, wallpaper files) | Caching *computational resources* (memoized engines, FFT setups, formatters) — those stay private state of the owning implementation (see docs/ARCHITECTURE.md "Analyzer memoization", #313) |
 
+## Dependency Chain — Adjacent Layers Only, No Skipping
+
+Within the VIPER lane, each layer depends only on the layer directly beneath it:
+
+```text
+View → Presenter → Interactor → UseCase → Repository → DataSource/DataStore → Gateway (OS boundary)
+```
+
+- **No layer skipping.** An upper layer must not consume a lower-lower layer
+  directly, even when `@Dependency` makes it a one-liner — an Interactor
+  holding a Gateway is a violation regardless of how convenient the DI graph
+  makes it (#337: `ConfigInteractor` → `ConfigWatchGateway` was refactored
+  into the adjacent chain).
+- **OS-boundary gateways are consumed at the DataSource layer.** Precedents:
+  `AudioTapDataSource → AudioTapGateway`, `ConfigDataSource →
+  ConfigWatchGateway`. When an upper layer needs OS-boundary behavior, thread
+  a contract through the adjacent layers as pass-throughs (e.g.
+  `watchChanges(onChange:)` on UseCase → Repository → DataSource) instead of
+  reaching down.
+- **Knowledge placement follows the chain too.** Path resolution, normalization,
+  and other persistence-shaped knowledge live in the DataSource; the layers
+  above see only the contract.
+
 ## CLI Command Pattern
 
 All commands follow: **inject → call → write → guard**. No exceptions.
 
@@ -106,6 +106,42 @@ Shared conventions:
   back to the raw title/artist -- never an unvalidated candidate guess --
   when nothing validates. See `docs/ARCHITECTURE.md` (Key Design Decisions,
   #308) for full detail.
+- Config hot-reloads without a daemon restart. `ConfigUseCase.reload()` keeps
+  the previous `AppStyle` in effect when the **required** structure fails to
+  validate (unreadable file, decode error in a core section, or a file that
+  resolves to defaults while it still exists) -- never regress on a bad edit.
+  A malformed **optional** `[ai]`/`[lyrics]` section instead degrades to `nil`
+  like startup and does not block a valid edit; `lyra healthcheck` still
+  reports it (the strictness is the `strictOptionalSections` flag on
+  `validate`/`tryDecode`, #330). The `ConfigWatchGateway` (Domain) /
+  `FileWatchGateway` (Support) pair watches the config's *parent directory*
+  (atomic saves rename the file) plus a re-armed file tier via
+  `DispatchSource`. The gateway is consumed at the **DataSource layer**:
+  `ConfigDataSourceImpl.watchChanges(onChange:)` owns target resolution
+  (config file, `includes`, foreign include parents) and per-event re-arming,
+  and the watch reaches the interactor only through `ConfigRepository` /
+  `ConfigUseCase` pass-throughs -- adjacent layers only, no layer skipping.
+  The directory watch arms whether or not the file exists yet, so a config
+  created after the daemon starts (`lyra config init`, a manual save) is
+  picked up as the initial load without a restart, as long as the config
+  directory exists at start (#329). The
+  `ConfigInteractor` module debounces watch events before calling
+  `reload()` and republishing the outcome over Combine. An invalid reload
+  is shown graphically (an amber "destabilized" geodesic sphere via
+  `ConfigStatusPresenter`/`ConfigStatusOverlay`) since a daemon has no
+  visible stderr. See `docs/ARCHITECTURE.md` (Key Design Decisions, #41) for
+  full detail. Header/Lyrics styling, the ripple/spectrum overlays (styling
+  plus the `enabled` toggle), the wallpaper source, and the screen selection
+  now all re-render live -- each Presenter subscribes once to `appStyleChanges`
+  and reflects the change in an idempotent `applyStyle()`, and the DisplayLink
+  fan-out always includes the ripple/spectrum frame handlers (their enabled
+  guard lives inside the handler, #41 PR3). The wallpaper reload diffs the
+  source and swaps the video via `replaceCurrentItem` on the same AVPlayer, so
+  the overlay never blacks out; removing all wallpaper tears the player down and
+  detaches the layer, restoring the transparent backing rather than leaving a
+  black surface; the screen reload re-runs `resolveLayout()` and restarts vacant
+  polling on a new selector/debounce (#41 PR4). Config hot-reload now covers
+  every visual element -- #41 is functionally complete.
 
 ## Testing Rules
 
@@ -122,8 +158,11 @@ Shared conventions:
 ## Change Checklist
 
 - When adding or removing modules, update `Package.swift`,
-  `DependencyInjection`, `docs/ARCHITECTURE.md`, `.claude/CLAUDE.md`, this
-  `AGENTS.md`, and `README.md`.
+  `DependencyInjection`, `docs/ARCHITECTURE.md`, this `AGENTS.md`, and
+  `README.md`. Update `.claude/CLAUDE.md` only when Build & Test commands
+  change or the layer chain itself changes — its architecture section is a
+  short summary + pointer, and `docs/ARCHITECTURE.md` is the canonical
+  reference (see `.claude/rules/module-checklist.md`).
 - Handler additions also need Entity result types, Domain protocols,
   `StandardOutput` support, CLI wiring, and tests.
 - Do not commit directly to `main`. Use branch -> PR -> merge.
 
@@ -118,6 +118,14 @@ let package = Package(
                 "Domain"
             ]
         ),
+
+        // ── FileWatchGateway ──
+        .target(
+            name: "FileWatchGateway",
+            dependencies: [
+                "Domain"
+            ]
+        ),
         .target(
             name: "AppKitScreenProvider",
             dependencies: [
@@ -244,6 +252,7 @@ let package = Package(
                 "DeveloperLog",
                 "TrackInteractor",
                 "ScreenInteractor",
+                "ConfigInteractor",
                 "WallpaperInteractor",
                 "SpectrumInteractor",
                 "ConfigUseCase",
@@ -267,6 +276,7 @@ let package = Package(
                 "SQLiteDataStore",
                 "DarwinGateway",
                 "CoreAudioTapGateway",
+                "FileWatchGateway",
                 "FrequencyAnalyzer",
                 "ProcessHandler",
                 "VersionHandler",
@@ -295,6 +305,13 @@ let package = Package(
                 .product(name: "Dependencies", package: "swift-dependencies"),
             ]
         ),
+        .target(
+            name: "ConfigInteractor",
+            dependencies: [
+                "Domain",
+                .product(name: "Dependencies", package: "swift-dependencies"),
+            ]
+        ),
         .target(
             name: "WallpaperInteractor",
             dependencies: [
@@ -415,6 +432,7 @@ let package = Package(
             name: "ConfigDataSource",
             dependencies: [
                 "Domain",
+                .product(name: "Dependencies", package: "swift-dependencies"),
                 .product(name: "Files", package: "Files"),
                 .product(name: "TOMLKit", package: "TOMLKit"),
             ]
@@ -511,6 +529,14 @@ let package = Package(
                 .product(name: "Dependencies", package: "swift-dependencies"),
             ]
         ),
+        .testTarget(
+            name: "ConfigInteractorTests",
+            dependencies: [
+                "ConfigInteractor",
+                "Domain",
+                .product(name: "Dependencies", package: "swift-dependencies"),
+            ]
+        ),
         .testTarget(
             name: "WallpaperInteractorTests",
             dependencies: [
@@ -567,6 +593,10 @@ let package = Package(
             name: "CoreAudioTapGatewayTests",
             dependencies: ["CoreAudioTapGateway"]
         ),
+        .testTarget(
+            name: "FileWatchGatewayTests",
+            dependencies: ["FileWatchGateway", "Domain"]
+        ),
         .testTarget(name: "EntityTests", dependencies: ["Entity"]),
         .testTarget(
             name: "AsyncRunnableCommandTests",
@@ -750,14 +780,29 @@ let package = Package(
             dependencies: [
                 "ConfigDataSource",
                 "Domain",
+                "FileWatchGateway",
+                .product(name: "Dependencies", package: "swift-dependencies"),
                 .product(name: "TOMLKit", package: "TOMLKit"),
             ]
         ),
+        .testTarget(
+            name: "ConfigHotReloadTests",
+            dependencies: [
+                "ConfigUseCase",
+                "ConfigInteractor",
+                "ConfigRepository",
+                "ConfigDataSource",
+                "Domain",
+                "Entity",
+                .product(name: "Dependencies", package: "swift-dependencies"),
+            ]
+        ),
         .testTarget(
             name: "LyricsDataSourceTests",
             dependencies: [
                 "LyricsDataSource",
                 "Domain",
+                "ConfigDataSource",
                 .product(name: "Dependencies", package: "swift-dependencies"),
                 .product(name: "Papyrus", package: "papyrus"),
             ]
 
@@ -107,6 +107,16 @@ Or create `~/.config/lyra/config.toml` (or `config.json`) manually. All fields a
 
 Alternative paths: `~/.lyra/config.toml`, `$XDG_CONFIG_HOME/lyra/config.toml`
 
+### Live reload
+
+The daemon watches the config directory for edits and re-validates on every save — no `lyra restart` needed to pick up a config file change. Saves are debounced briefly to coalesce rapid writes, then applied automatically. The watch arms even when no config file exists yet, so a config created after the daemon starts (via `lyra config init` or a manual save) is picked up without a restart, as long as its directory (`~/.config/lyra`) already exists.
+
+This now covers every visual element: config validation, the header and lyrics styling (fonts, colors, sizes, decode effect, and artwork all re-render live), the lyrics `[lyrics] fallback_command`/`timeout_ms` settings (re-read on every fallback invocation), the ripple and spectrum overlays (their styling and their `enabled` toggle both take effect live), the wallpaper source (swapping the video, changing playback mode, or removing it entirely all apply live without blacking out the overlay), and the screen selection (`[screen]` selector and debounce). No `lyra restart` is required for any config edit.
+
+If an edit breaks the config's required structure (invalid TOML/JSON, or bad values in the core text/wallpaper/spectrum sections), lyra keeps the last valid style in effect rather than falling back to defaults or crashing. Since a background daemon has no visible terminal to log an error to, a small amber "shattered" sphere appears in the corner of the overlay to flag that the last edit wasn't applied — fix the file and save again to clear it.
+
+A malformed optional `[ai]` or `[lyrics]` section is tolerated instead of blocking the whole edit: that section is skipped while the rest of the valid config still applies, exactly as it does at startup (so no "shattered" sphere appears for it). `lyra healthcheck` still reports a malformed `[ai]`/`[lyrics]` so the problem stays discoverable.
+
 ### Top-level
 
 | Key | Type | Default | Description |
 
@@ -87,6 +87,7 @@ import Foundation
 
     private struct UITestWallpaperInteractor: WallpaperInteractor {
         var playbackMode: WallpaperPlaybackMode { .cycle }
+        var wallpaperSource: WallpaperStyle? { nil }
         func resolvedWallpapers() -> AsyncStream<ResolvedWallpaperItem> {
             AsyncStream { $0.finish() }
         }
 
@@ -9,7 +9,10 @@ import Views
 public final class AppRouter {
     private let bootstrap: AppDependencyBootstrap
     private let windowFactory:
-        @MainActor (ScreenLayout, HeaderPresenter, LyricsPresenter, RipplePresenter, SpectrumPresenter, WallpaperPresenter)
+        @MainActor (
+            ScreenLayout, HeaderPresenter, LyricsPresenter, RipplePresenter, SpectrumPresenter, WallpaperPresenter,
+            ConfigStatusPresenter?
+        )
             -> any OverlayWindow
     private let frameSchedulerFactory: @MainActor (@escaping @MainActor (Double) -> Void) -> any FrameScheduler
     private var appPresenter: AppPresenter?
@@ -18,6 +21,7 @@ public final class AppRouter {
     private var wallpaperPresenter: WallpaperPresenter?
     private var ripplePresenter: RipplePresenter?
     private var spectrumPresenter: SpectrumPresenter?
+    private var configStatusPresenter: ConfigStatusPresenter?
 
     private var appWindow: (any OverlayWindow)?
     private var frameScheduler: (any FrameScheduler)?
@@ -28,19 +32,30 @@ public final class AppRouter {
         DisplayLinkDriver(onFrame: onFrame)
     }
 
+    static func defaultWindowFactory(
+        layout: ScreenLayout,
+        headerPresenter: HeaderPresenter,
+        lyricsPresenter: LyricsPresenter,
+        ripplePresenter: RipplePresenter,
+        spectrumPresenter: SpectrumPresenter,
+        wallpaperPresenter: WallpaperPresenter,
+        configStatusPresenter: ConfigStatusPresenter?
+    ) -> any OverlayWindow {
+        AppWindow(
+            initialLayout: layout,
+            headerPresenter: headerPresenter,
+            lyricsPresenter: lyricsPresenter,
+            ripplePresenter: ripplePresenter,
+            spectrumPresenter: spectrumPresenter,
+            wallpaperPresenter: wallpaperPresenter,
+            configStatusPresenter: configStatusPresenter
+        )
+    }
+
     public convenience init(launchEnvironment: AppLaunchEnvironment = .current) {
         self.init(
             bootstrap: AppDependencyBootstrap(launchEnvironment: launchEnvironment),
-            windowFactory: { layout, headerPresenter, lyricsPresenter, ripplePresenter, spectrumPresenter, wallpaperPresenter in
-                AppWindow(
-                    initialLayout: layout,
-                    headerPresenter: headerPresenter,
-                    lyricsPresenter: lyricsPresenter,
-                    ripplePresenter: ripplePresenter,
-                    spectrumPresenter: spectrumPresenter,
-                    wallpaperPresenter: wallpaperPresenter
-                )
-            },
+            windowFactory: Self.defaultWindowFactory,
             frameSchedulerFactory: Self.defaultFrameSchedulerFactory
         )
     }
@@ -49,7 +64,8 @@ public final class AppRouter {
         launchEnvironment: AppLaunchEnvironment,
         windowFactory:
             @escaping @MainActor (
-                ScreenLayout, HeaderPresenter, LyricsPresenter, RipplePresenter, SpectrumPresenter, WallpaperPresenter
+                ScreenLayout, HeaderPresenter, LyricsPresenter, RipplePresenter, SpectrumPresenter, WallpaperPresenter,
+                ConfigStatusPresenter?
             ) -> any OverlayWindow,
         frameSchedulerFactory: @escaping @MainActor (@escaping @MainActor (Double) -> Void) -> any FrameScheduler
     ) {
@@ -64,7 +80,8 @@ public final class AppRouter {
         bootstrap: AppDependencyBootstrap,
         windowFactory:
             @escaping @MainActor (
-                ScreenLayout, HeaderPresenter, LyricsPresenter, RipplePresenter, SpectrumPresenter, WallpaperPresenter
+                ScreenLayout, HeaderPresenter, LyricsPresenter, RipplePresenter, SpectrumPresenter, WallpaperPresenter,
+                ConfigStatusPresenter?
             ) -> any OverlayWindow,
         frameSchedulerFactory: @escaping @MainActor (@escaping @MainActor (Double) -> Void) -> any FrameScheduler
     ) {
@@ -93,15 +110,22 @@ public final class AppRouter {
             self.ripplePresenter = ripplePresenter
             let spectrumPresenter = SpectrumPresenter()
             self.spectrumPresenter = spectrumPresenter
+            let configStatusPresenter = ConfigStatusPresenter()
+            self.configStatusPresenter = configStatusPresenter
 
             headerPresenter.start()
             lyricsPresenter.start()
             ripplePresenter.start()
             spectrumPresenter.start()
             wallpaperPresenter.start()
+            // ConfigStatusPresenter owns the ConfigInteractor lifecycle (arming the config-file
+            // watch). Start it last so all `appStyleChanges` subscribers above are live before
+            // any watch-triggered reload event is published.
+            configStatusPresenter.start()
 
             let window = windowFactory(
-                layout, headerPresenter, lyricsPresenter, ripplePresenter, spectrumPresenter, wallpaperPresenter)
+                layout, headerPresenter, lyricsPresenter, ripplePresenter, spectrumPresenter, wallpaperPresenter,
+                configStatusPresenter)
             appWindow = window
             window.show()
 
@@ -113,22 +137,25 @@ public final class AppRouter {
                 window?.attachPlayerLayer(for: player)
                 window?.applyWallpaperScale(wallpaperPresenter?.wallpaperScale ?? 1.0)
             }
+            wallpaperPresenter.onPlayerCleared { [weak window] in
+                window?.detachPlayerLayer()
+            }
             wallpaperPresenter.onWallpaperScaleChange { [weak window] scale in
                 window?.applyWallpaperScale(scale)
             }
 
-            // Only enabled features pay a per-frame cost: each optional
-            // handler is included in the frame fan-out only when its feature
-            // is on, so a disabled ripple/spectrum adds zero work per tick.
+            // Ripple and spectrum handlers are always installed so enabling either
+            // at runtime resumes its per-frame work without rebuilding the fan-out
+            // (#41 PR3). Each bails cheaply while its feature is inactive —
+            // `idle()` on an enabled guard, `tick()` on its capturing/residue guard
+            // — so a disabled feature still adds no real per-frame cost (#252/#258).
             let frameHandlers: [@MainActor @Sendable (Double) -> Void] = [
-                ripplePresenter.isEnabled
-                    ? { @MainActor @Sendable [weak self] _ in self?.ripplePresenter?.idle() } : nil,
-                spectrumPresenter.isEnabled
-                    ? { @MainActor @Sendable [weak self] interval in
-                        self?.spectrumPresenter?.tick(frameInterval: interval)
-                    } : nil,
+                { @MainActor @Sendable [weak self] _ in self?.ripplePresenter?.idle() },
+                { @MainActor @Sendable [weak self] interval in
+                    self?.spectrumPresenter?.tick(frameInterval: interval)
+                },
                 { @MainActor @Sendable [weak self] _ in self?.lyricsPresenter?.updateActiveLineTick() },
-            ].compactMap { $0 }
+            ]
             let onFrame: @MainActor @Sendable (Double) -> Void = { interval in
                 for handler in frameHandlers { handler(interval) }
             }
@@ -157,6 +184,13 @@ public final class AppRouter {
         spectrumPresenter?.stop()
         defer { spectrumPresenter = nil }
 
+        // ConfigStatusPresenter owns the ConfigInteractor lifecycle: its
+        // stop() disarms the watch. Because the presenter was constructed
+        // inside the bootstrap scope in start(), its `@Dependency` resolves the
+        // same interactor instance here without a manual `withBootstrap` wrap.
+        configStatusPresenter?.stop()
+        defer { configStatusPresenter = nil }
+
         frameScheduler?.stop()
         defer { frameScheduler = nil }
 
 
@@ -7,6 +7,7 @@ protocol OverlayWindow: AnyObject {
     func show()
     func applyLayout(_ layout: ScreenLayout)
     func attachPlayerLayer(for player: AVPlayer)
+    func detachPlayerLayer()
     func applyWallpaperScale(_ scale: Double)
     func close()
 }
Original file line number	Diff line number	Diff line change
`@@ -87,6 +87,7 @@ import Foundation`
`87`	`87`
`88`	`88`	`private struct UITestWallpaperInteractor: WallpaperInteractor {`
`89`	`89`	`var playbackMode: WallpaperPlaybackMode { .cycle }`
	`90`	`+ var wallpaperSource: WallpaperStyle? { nil }`
`90`	`91`	`func resolvedWallpapers() -> AsyncStream<ResolvedWallpaperItem> {`
`91`	`92`	`AsyncStream { $0.finish() }`
`92`	`93`	`}`
Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,7 @@ protocol OverlayWindow: AnyObject {`
`7`	`7`	`func show()`
`8`	`8`	`func applyLayout(_ layout: ScreenLayout)`
`9`	`9`	`func attachPlayerLayer(for player: AVPlayer)`
	`10`	`+ func detachPlayerLayer()`
`10`	`11`	`func applyWallpaperScale(_ scale: Double)`
`11`	`12`	`func close()`
`12`	`13`	`}`