Skip to content

Free, open-source Windows optimization tool for performance, privacy, and simplicity.

docs: rewrite AGENTS.md as a condensed, current guide

fatDuck9df4835b5157
diff --git a/AGENTS.md b/AGENTS.md
index fbdd941..fc3af51 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,204 +1,131 @@
# Repository Guidelines
-## Windows-Only WPF App
-- **Windows-only**: Build/run/test only on Windows. Target framework: `net10.0-windows` with `UseWPF=true`, deliberately without a Windows SDK version: a versioned one makes the SDK reference the CsWinRT projection, which puts a 50 MB `Microsoft.Windows.SDK.NET.dll` into every publish for WinRT APIs this app does not call. `CA1416` (platform compatibility) is silenced — all code is Windows-only.
-- **Runs as admin**: `app.manifest` sets `requireAdministrator` UAC level. Tests that modify system settings or registry need admin too.
-- **Solution format**: `.slnx` (not `.sln`).
-- **Data directory**: `%LocalAppData%\optimizerDuck\` — holds revert files (`Revert/`), resources (`Resources/`), downloads (`Resources/Downloads/`), assets (`Resources/Assets/`), crash logs (`Crashes/`).
-- **Version**: Defined in `optimizerDuck.csproj` (`<Version>`). Don't hardcode it elsewhere; read it from the project file.
-
-## Build, Test, Run Commands
-- `dotnet restore optimizerDuck.slnx` — restore dependencies.
-- `dotnet build optimizerDuck.slnx --configuration Release --no-restore` — CI-aligned build.
-- `dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build` — run all tests.
-- `dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build --filter "FullyQualifiedName~TestName"` — run a single test.
+Windows-only WPF desktop app that optimizes Windows. Read this before changing code.
+
+## Hard rules
+- **Windows only.** `optimizerDuck` targets `net10.0-windows` with `UseWPF=true` and deliberately **no Windows SDK version in the TFM**: a versioned one makes the SDK reference the CsWinRT projection and ships a 50 MB `Microsoft.Windows.SDK.NET.dll` for WinRT APIs this app never calls. `CA1416` is silent because every path is Windows-only. (`optimizerDuck.Test` does carry `10.0.17763.0`.)
+- **Elevated.** `app.manifest` requests `requireAdministrator`. A test that writes the registry, a service or a scheduled task needs an elevated shell too.
+- **Two projects, nothing else.** `optimizerDuck/` (the app) and `optimizerDuck.Test/`, in `optimizerDuck.slnx` (not `.sln`). Never create a top-level directory outside them.
+- **One implementation per Windows operation.** Fix behaviour in the owner, never in a copy. See Providers.
+- **One execution path.** Every system-changing run goes through `OperationRunner`. Never add a second framework.
+- **No hardcoded UI strings.** `Loc.Instance["Key"]` in C#, `Translations.KeyName` in XAML. Add keys to `Resources/Languages/Translations.resx`.
+- **A warning fails the build** (`TreatWarningsAsErrors` + `EnforceCodeStyleInBuild` in both project files; the severity table in `.editorconfig` decides). `AnalysisMode=All` is deliberately off.
+
+## Commands
+- `dotnet restore optimizerDuck.slnx`
+- `dotnet build optimizerDuck.slnx --configuration Release --no-restore` — the CI-aligned gate.
+- `dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build` — all tests. Add `--filter "FullyQualifiedName~TestName"` for one.
- `dotnet run --project optimizerDuck/optimizerDuck.csproj` — run locally (needs admin).
-- `publish.bat portable` or `publish.bat single --skip-tests` — create release artifacts.
-- `csharpier format .` — format all code with CSharpier (`csharpier check .` to verify without writing).
- - Invoke it as `csharpier`, never `dotnet csharpier`: it is a global tool, and `dotnet csharpier` fails with
- "command not found", which reads like the tool is missing when it is not.
- - The editor runs CSharpier on file change here, so a file you touch can come back with unrelated code lines
- reflowed into the house style. That is the formatter, not your edit.
-
-## Project Structure
-- `optimizerDuck/` — WPF app (single project, no sub-projects):
- - `Domain/` — models, interfaces, attributes (no UI deps)
- - `Abstractions/` — `IOptimization`, `ICustomizeSetting`, `IRevertStep`, `ICustomizeCategory`, `IOptimizationCategory`, `IWindow`
- - `Attributes/` — `[Optimization]`, `[CustomizeSetting]`, `[OptimizationCategory]`, `[CustomizeCategory]`
- - `Conditions/` — compatibility condition system: `ICondition`, `ConditionBase`, `ConditionResult`, `ConditionState`, `ConditionValidation`, `WindowsBuilds`, and `BuiltIn/` (Windows version, CPU/GPU brand, min RAM, registry-key/service existence conditions)
- - `Exceptions/` — `StepExecutionException`
- - `Execution/` — `OpCall` (explicit per-operation context: changes, logger, cancellation), `ChangeSet` (thread-safe change collector) + `Change` (one recorded step, also the step result shown to the user), `OpResult` (single-operation result), `OperationSubject` (the Id, key and English log name a run and its record belong to), `OperationRequest` (one run: subject, display name, logger, whether its compensation is persisted) + `RevertPersistence`, `ToolSubjects` (the fixed subjects of the built-in tools)
- - `Customize/Categories/` — Desktop, Gaming, Preferences, SystemFeatures (nested setting classes)
- - `Optimizations/Categories/` — Performance, SecurityAndPrivacy, Gpu, PowerManagement, BloatwareAndServices, UserExperience, AI (nested optimization classes)
- - `Optimizations/Models/` — `BaseOptimization`, `ApplyResult`, `OptimizationContext`, `OptimizationResult`
- - `Optimizations/Models/Services/` — `RegistryItem`, `ServiceItem` (+ `ServiceStartupType`), `ShellResult`
- - `Optimizations/Models/Power/` — `PowerScheme`, `PowerSettingGroup`, `PowerSetting`, `PowerSource`, `PowerValueKind`, `PowerPossibleValue`, `PowerPlanError` (raw-vs-semantic-vs-display: numeric AC/DC stay numeric)
- - `Optimizations/Models/Bloatware/` — `AppXPackage`
- - `Optimizations/Models/Cleanup/` — `CleanupItem`
- - `Optimizations/Models/ScheduledTask/` — `ScheduledTaskModel`
- - `Optimizations/Models/StartupManager/` — `StartupApp`, `StartupTask`
- - `Customize/Models/` — `BaseCustomizeSetting`, `RegistryToggle`, `RegistryBinding`, `CustomizeRefreshScope`, `SettingOption`, `CustomizeControlType`, `RecommendationState`, `CustomizeRecommendationResult`
- - `Revert/` — `RevertData`, `RevertResult`
- - `Revert/Steps/` — `RegistryRevertStep`, `ServiceRevertStep`, `ScheduledTaskRevertStep`, `ShellRevertStep`, `UsbPowerRevertStep`, `PowerPlanRevertStep`, `PowerSettingRevertStep`
- - `Configuration/` — `AppSettings`
- - `UI/` — enums: `OptimizationRisk`, `OptimizationTags` (flags), `OptimizationCategoryOrder`, `CustomizeOrder`, `OptimizationSuccessResult`, `OptimizationState` (ObservableObject with relative-time display), `RiskVisual`, `ProcessingProgress`, `LanguageOption`
- - `Optimizations/Models/Services/` — also `RegistryValues` (shared value equality), `ShellPolicy` (shell success/error policy), `ShellResult`
- - `Services/` — business logic:
- - `Conditions/` — `ConditionEvaluator` (static, fail-open evaluation)
- - `Configuration/` — `ConfigManager`, `LanguageManager`
- - `Customize/` — `CustomizeRegistry` (reflection-based discovery), `CustomizationExecutor` (debounce + sequential serialization for setting writes)
- - `Optimization/` — `OptimizationRegistry`, `OptimizationService`, `OperationRunner` (the one lifecycle a system-changing run takes: invoke the work, classify the outcome from the recorded steps, write the record, persist revert data when the subject asks for it), `OptimizationValidation` (fail-fast Id checks at startup)
- - `System/Primitives/` — `RegistryService`, `ScheduledTaskService`, `ServiceProcessService` are **static** (stateless); `ShellService` + `ProcessRunner` are DI singletons (stateful; `ShellService` reads the timeout live from settings). Those four take an explicit `OpCall`, record into `call.Changes`, log via `call.Logger`, return `OpResult`. `ShellMapping` centralises cmd/PowerShell argument building and result mapping. `PowerPlanChanges` is the single edge recorder turning lean `PowerPlanService` results into `Change` + revert step + retry (categories never hand-roll power steps). Service startup types are read and written through the Service Control Manager inside `ServiceProcessService` (no `sc.exe`, no START_TYPE parsing). `RecycleBinService`, `HibernationService` and `UsbPowerService` are **static** primitives owning one Windows operation each (shell Recycle Bin APIs, the documented power information callback, `root\wmi` device power) and fail open instead of throwing.
- - `ApplicationServiceCollectionExtensions.cs` — `AddOptimizerApplication(IConfiguration)`: the whole application graph, separated from `App.xaml.cs` so a test can build it
- - `Revert/` — `RevertManager` (atomic file-based revert data persistence)
- - `System/` — `RegistryWatcher` (+ `IRegistryWatcher`), `SystemInfoService` (defines `SystemInfo` + models), `StreamService`, `UpdaterService`, `CrossPageEventBus`, `CrossPageEvents`, `PowerPlanService` (lean native core: reads take ids, writes take `ILogger? = null` and record nothing; single owner of power **scheme** interop), `SystemRestoreService` (same lean shape; single owner of every System Restore WMI call, reusable by a future restore-point tool)
- - `UI/` — `BloatwareService`, `DiskCleanupService`, `StartupManagerService` (reads the packaged apps that declare a startup task from the per-user AppModel repository and their state from `AppModel\SystemAppData`, so no WinRT projection is needed)
- - `UI/` — XAML pages, ViewModels, windows, controls, dialogs, styles. `ToolRunPresenter` runs one tool action and reports its outcome (progress dialog, retry dialog, snackbar), so every tool page runs and reports an action the same way.
- - `Common/` — extensions, helpers, converters:
- - `Helpers/` — `Shared.cs` (constants, paths, SafeApps/CautionApps sets), `ReflectionHelper.cs`, `SystemRefreshService.cs` (P/Invoke for Windows refresh), `EmbeddedResourceHelper.cs`, `WmiHelper.cs`, `GitHubSourceHelper.cs`, `ThemeResource.cs`, `HttpClientFactory.cs`, `UiThread.cs`, `UserErrorSurface.cs` (reports one unhandled failure to the user, once per exception, and never throws)
- - `Converters/` — WPF value converters (BooleanToVisibility, MBToGB, ...)
- - `Extensions/` — `StringExtensions`, `CustomizePageRegistryExtensions`, `OptimizationPageRegistryExtensions`, `LanguageExtensions`
- - `Resources/` — images, embedded assets, locale files
- - `Languages/` — `Translations.resx` (default English) + locale variants. Do **not** hardcode the list of languages; the authoritative lists are the files in this folder and `Languages` in `UI/ViewModels/Pages/SettingsViewModel.cs`.
-- `optimizerDuck.Test/` — xUnit v3 tests (single test project with `InternalsVisibleTo`)
-- Do **not** create top-level directories outside these two project folders.
-
-## Key NuGet Packages
-- `CommunityToolkit.Mvvm` 8.4.2 — MVVM source generators (`[ObservableProperty]`, `[RelayCommand]`)
-- `WPF-UI` + `WPF-UI.DependencyInjection` 4.3.0 — Fluent Design controls + navigation
-- `Microsoft.Extensions.Hosting` + `Microsoft.Extensions.DependencyInjection` 10.0.10 — DI / hosted service wiring
-- `Newtonsoft.Json` 13.0.4 — JSON serialization for revert data
-- `Serilog` 4.4.0 + `Serilog.Extensions.Hosting` + `Serilog.Sinks.File` — structured logging
-- `TaskScheduler` 2.12.2 — Windows scheduled task management
-- `System.Management.Automation` 7.6.4 — PowerShell host integration
-- `xunit.v3` 3.2.2 — test framework (with global using `Xunit` in test csproj)
-
-> Package versions live in `optimizerDuck.csproj` / `optimizerDuck.Test.csproj` — verify there rather than trusting this snapshot.
-
-## Optimization & Customize Discovery (Reflection, No Manual Registration)
-- **New optimizations**: Create a **nested class** inside the relevant category class (e.g., `Domain/Optimizations/Categories/Performance.cs`), extend `BaseOptimization`, decorate with `[Optimization(Id = "guid", Risk = ..., Tags = ..., Condition = typeof(...)?)]`. This is the only optimization path.
-- **New customize settings**: Same nesting pattern inside `Domain/Customize/Categories/`, extend `BaseCustomizeSetting`, decorate with `[CustomizeSetting(Section = ..., Icon = ..., Recommendation = ..., Condition = typeof(...)?)]`. `Icon` is required (`SymbolRegular` enum). `Section` can be a string or enum value. `Recommendation` can be `On`, `Off`, `Depends`, `Experimental`, or `None`.
-- **Category classes**: Decorate with `[OptimizationCategory(typeof(PageClass))]` or `[CustomizeCategory(PageType = typeof(PageClass))]`.
-- **Discovery**: `ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` scans assemblies whose name starts with `optimizerDuck` — no DI registration array to update. Results are cached in `_implementationCache`.
-- **Provider services**: stateless services are static (`RegistryService`, `ServiceProcessService`, `ScheduledTaskService`) — call directly. `ShellService` + `ProcessRunner` are DI singletons, reached from optimizations as `context.Shell`. All take an explicit `OpCall`, record into `call.Changes`, return `OpResult`. Exception: `PowerPlanService` is a lean DI singleton — reads take ids, writes take `ILogger? = null` and record nothing (named record results); `PowerPlanChanges` records at the edge instead.
-- **Results**: Optimizations end `ApplyAsync` with `return context.Changes.ToApplyResult();`. Do not manually construct `ApplyResult` except for early-out failures.
-- **Single execution path**: `BaseOptimization` + `OptimizationContext` (`OpCall`) + static providers + `ShellService`, orchestrated by `OperationRunner`. Every system-changing run goes through it: an optimization (`OptimizationService.ApplyAsync` builds the `OperationRequest`) and a tool action (`ToolRunPresenter` builds it) differ only in their subject and in whether revert data is persisted. There is no second framework — do not add one, and do not write a second implementation of an existing Windows operation.
-- **One implementation per Windows operation**: `RegistryService`/`ServiceProcessService`/`ScheduledTaskService`/`ShellService` are the single source of truth (plus the shared `RegistryValues`, `ShellMapping`), `PowerPlanService` owns power-scheme interop, `SystemRestoreService` owns System Restore, and the static primitives (`RecycleBinService`, `HibernationService`, `UsbPowerService`) own one Windows operation each. Fix behaviour there, not in a copy.
-- **DI**: register through `AddOptimizerApplication(configuration)` (the whole app graph); `App.xaml.cs` only builds the host. The host sets `ValidateOnBuild`/`ValidateScopes`, so a broken registration fails at startup instead of at Apply time — keep it that way.
-- **Skip policy**: a provider whose mutation needs a privilege it may not have, has a side effect beyond the value it sets, or can be refused when called a second time reads the current state first and records a skip when the machine already matches, without calling the mutation (`RegistryService`, `ServiceProcessService`, `ScheduledTaskService`, `PowerPlanChanges`, hibernation, USB). An item never decides this on its own: skipping at the item level drops the step from the record entirely.
-- **Kinds**: `Change` (modified, carries compensation), `Skip` (already correct), `NotApplicable` (nothing on this machine to act on), `Refused` (Windows refused; not a failure), `Irreversible` (no way back). `DidApplyAnything` (only `Change`, and what revert persistence is gated on) is narrower than `ModifiedSystem` (`Change` + `Irreversible`, and what tells a change from nothing to do), so a run whose only step was irreversible is a success rather than nothing to do, and a run that recorded no change at all is reported as nothing to do rather than as a failure.
-- **The record of a run**: `OperationRunner` writes what a run did to `%LocalAppData%\optimizerDuck\History\{id}.json` (one file per subject, atomic, best effort, never part of the revert data). An optimization and a built-in tool both write one, under the fixed ids in `ToolSubjects`. `ChangeRecordStore` reads it back for the details view and for a retry's attempt counts, and the applied badge's summary comes from it.
-- **Per-step failure policy**: providers record a failed `Change` with an error and (where a retry can help) a retry action; they do not throw. Power failures record the same way via `PowerPlanChanges` (the service itself only returns diagnostics). Only truly unrecoverable state throws. `OperationRunner` persists partial work with `CancellationToken.None` and builds the `OptimizationResult`; an exception from a run is recorded as a failed step named for the user.
-- **Preloading**: `OptimizationRegistry.PreloadOptimizationsAsync()` / `EnsurePreloadedAsync()` (and `CustomizeRegistry.PreloadCategoriesAsync()` / `EnsurePreloadedAsync()`) run reflection discovery on a background thread. `App.xaml.cs` preloads at startup; the Optimize/Customize pages call `EnsurePreloadedAsync()` before binding.
-
-## Condition System (Compatibility Gating)
-- Conditions live in `Domain/Conditions/` (`ICondition`, `ConditionBase`, `ConditionResult`, `ConditionState`, `ConditionValidation`, `WindowsBuilds`, `BuiltIn/`). They're evaluated by the static `Services/Conditions/ConditionEvaluator.cs`.
-- `[Optimization]` and `[CustomizeSetting]` both accept an optional `Condition = typeof(SomeCondition)` where the type implements `ICondition` with a public parameterless constructor.
-- `ConditionState` = `Available` | `Unsupported` | `Error`. Only `Unsupported` blocks an item, and only when the item isn't already applied (or hidden by the user). `Error` and an unpopulated `SystemInfo` (`IsUnknown`) **fail open** (never hide).
-- `ConditionValidation.Validate(...)` runs at discovery time to fail fast on misconfigured condition metadata.
-- Custom conditions return `ConditionResult.Available` / `ConditionResult.Unsupported(titleProvider, descriptionProvider)` / `ConditionResult.Error()`. User-facing text must go behind localization providers (`() => Loc.Instance[...]`).
-
-## Revert System
-- **File-based**: Each applied optimization creates `%LocalAppData%\optimizerDuck\Revert\{optimizationId}.json`. Applied state is inferred from file presence on disk.
-- **Atomic writes**: `RevertManager` writes to `.tmp` via `FileStream(WriteThrough)` + `Flush(flushToDisk: true)`, then `File.Replace` for crash safety. Stale `.tmp` files are swept at startup (`RemoveOrphanedTempFiles`).
-- **Concurrent access**: Per-file `SemaphoreSlim` locks with 30-second timeout prevent race conditions. Lock entries are never disposed while in use.
-- **Compact layout**: only successful steps persist, each with a fresh index; no null gaps. Re-apply appends new entries; recovered retry steps append via `AppendRevertStepAsync` (never overwrite — LIFO revert still ends at the original backup).
-- **Step types**: `RegistryRevertStep`, `ServiceRevertStep`, `ScheduledTaskRevertStep`, `ShellRevertStep`, `UsbPowerRevertStep`, `PowerPlanRevertStep`, `PowerSettingRevertStep`. Each verifies its own effect inside `ExecuteAsync` (registry read-back, service re-query, task state re-check, power re-read). Access-denied is failure, never success. Missing `OriginalEnabled` throws (fail-closed).
-- **Unknown types**: persisted data with an unregistered step type becomes a failing step with a clear message (never silently skipped); raw payload round-trips.
-- **Step registry**: Revert step deserialization uses reflection-based `_stepRegistry` (`ConcurrentDictionary`). New step types auto-register by implementing `IRevertStep` with a static `FromData(JObject)` method.
-- **Retry**: `OptimizationService.RetryFailedStepsWithResultsAsync()` re-invokes `Retry` with a fresh `OpCall` and persists recovered steps via `AppendRevertStepAsync`. The optimization page's dialog and `ToolRunPresenter` both call it; reverting an optimization passes a `RevertManager` and a tool passes none, so a retried tool step writes no revert data.
-- **Key methods**: `SaveRevertDataAsync()`, `RevertAsync()`, `AppendRevertStepAsync()`, `RemoveRevertStepsAtIndexesAsync()`, `IsAppliedAsync(id)`, `GetRevertDataAsync(id)`, `ClearAllRevertData()`, `RemoveOrphanedTempFiles()`.
-
-## Customize Setting API Notes
-- `RegistryToggle` uses `OnValues` / `OffValues` (lists; `null` = key absent) + `DefaultValue`, `IsOptional`, `ValueKind`. There is no `OnValue`/`OffValue`/`TreatMissingAsDefault`.
-- Dropdown settings override `ControlType => CustomizeControlType.Dropdown` and `GetOptions()` returning `SettingOption`s built with `Option(key, regPath, regName, value)` or `Option(key, value, params RegistryBinding[])`. The base class auto-reads/auto-writes via bindings and shows a "Custom"/"Not set" fallback for out-of-scope values.
-- When overriding `ApplyAsync`, call `await ExecutePostActionAsync()` (guarded by `NeedsPostAction`) yourself.
-
-## Coding & Style
-- Nullable enabled, file-scoped namespaces, implicit usings.
-- Indent: 4 spaces. PascalCase types/members, `_camelCase` private fields, `camelCase` locals/params.
-- Max line length: 100 characters (enforced by `.editorconfig`).
-- **No hardcoded UI strings** — use `Loc.Instance["Key"]` (C#) or `Translations.KeyName` (XAML bindings). Add new keys to `Resources/Languages/Translations.resx`.
-- **Keep comments sparse** — existing code has almost none; do not add unnecessary ones.
-- DI via `Microsoft.Extensions.Hosting` + `CommunityToolkit.Mvvm`. Pages + ViewModels registered as singletons in `App.xaml.cs`.
-- `optimizerDuck.csproj` has `<InternalsVisibleTo Include="optimizerDuck.Test" />` — test project can access internal members.
-- Category pages auto-register via `services.AddAllCustomizeCategoryPages()` and `services.AddAllOptimizationPages()`.
-- `ProcessRunner` + `ShellService` come from DI; there is no init step. `OperationRunner` creates the per-run `ChangeSet`. Revert steps that run commands receive the app shell service from `RevertManager` so the configured timeout applies to undo.
-- The full build/format/analysis gate is: `dotnet build ... Release` (the build **fails on any warning**: `TreatWarningsAsErrors` + `EnforceCodeStyleInBuild` are set in both project files, so the severity table in `.editorconfig` decides), then `dotnet test`, then `csharpier check .`. `AnalysisMode=All` is deliberately not enabled; the measured reason is in `.editorconfig`.
-- `WmiHelper.Initialize()` registers WMI cleanup for abnormal termination.
-
-## Localization (All Locales)
-Applies to every supported and future locale. Goal is natural localization, not word-for-word translation: each locale should read as if written by a native speaker who understands Windows, PC hardware, system optimization, and modern desktop UI.
-- Technical terms: keep English where that locale's Windows/PC users expect it (e.g. in Vietnamese: SSD, HDD, RAM, CPU, GPU, Driver, Registry, BIOS, UEFI, PowerShell — never literal "Trình điều khiển" for Driver); translate concepts with natural localized equivalents where they exist (e.g. vi "Memory Integrity" → "Tính toàn vẹn bộ nhớ"). Apply the same reasoning independently per locale: conventions differ per language, never force one locale's choice onto another.
-- No awkward literal translations: rewrite unnatural phrasing, never copy English sentence structure that sounds wrong in the target language. Meaning and intent outrank word order.
-- Technical terms stay, surrounding language translates: keep established terms (hardware, Windows, APIs, protocols, formats, gaming/performance terms) while the rest of the sentence is fluent target language.
-- Context-dependent: same source term may need different translations per context (e.g. "Startup" as manager vs. at-startup behavior). Consistency order: correct meaning, then natural language, then established terminology, then cross-app consistency.
-- UI style: modern, clean, concise, scannable, professional without corporate stiffness. Prefer shorter wording when meaning is preserved; never pad to match source length.
-- No em dashes in any locale: restructure with commas, periods, colons, or parentheses natural to the target language.
-- Format integrity: preserve `{0}` placeholders verbatim and in order, escape XML specials, keep `xml:space="preserve"`. Neutral `Translations.resx` is the key source; every key must exist in all locale files (guarded by `EveryNeutralKey_ResolvesInEverySupportedLanguage`).
-
-## Testing (xUnit v3, Integration-Style)
-- **No mocking libraries** — all test doubles are hand-written (`FakeOptimization`, `TestOptimization`, etc.) implementing interfaces directly.
-- **Real I/O**: Tests use real filesystem (revert JSON files), real registry (`HKCU\Software\TestOptimizerDuck*`), real process execution (CMD/PowerShell).
-- **STA thread**: Tests involving WPF components must use `RunInStaThreadAsync` helper (STA thread + `TaskCompletionSource`). The test project itself defines this helper — add it if missing.
-- **Logging**: Use `NullLogger<T>.Instance` / `NullLoggerFactory.Instance` for DI logging parameters.
-- **Test naming**: `{Method}_{Scenario}_{ExpectedResult}` (e.g., `ApplyAsync_Success_PersistsRevertDataFile`).
-- **Cleanup**: Use `try/finally` or `IDisposable` for test artifact cleanup (revert files, registry keys). Tests that create revert data must clean up both `{id}.json` and `{id}.json.tmp`.
-- **No coverage gate** — prioritize meaningful unit coverage for changed logic.
-- **CI test command** uses `--blame-hang --blame-hang-timeout 30s` — tests must not hang longer than 30s.
-- **Test project packages**: `Microsoft.NET.Test.Sdk` 18.6.0, `xunit.v3` 3.2.2, `coverlet.collector` 10.0.1.
-
-## Shell Service Details
-- `ShellService.CMDAsync()` and `PowerShellAsync()` run commands in cmd.exe / PowerShell (`-EncodedCommand`). `QueryCMDAsync()` / `QueryPowerShellAsync()` run without recording a change.
-- Async variants accept an optional revert step (from `revertCommand` string) that gets saved for undo.
-- `ShellPolicy` class provides customizable success criteria (default: exit code 0). Use `ShellPolicy.SuccessExitCodes()` or `ShellPolicy.SuccessExitCodeRange()` for non-standard exit codes.
-- Default timeout: 120 seconds (configurable via `AppSettings.Optimize.ShellTimeoutMs`).
-- UTF-8 encoding is forced for both stdout and stderr.
-
-## Registry Service Details
-- Supports multiple root key prefixes: HKLM, HKLM:, HKEY_LOCAL_MACHINE, HKCU, HKCU:, HKEY_CURRENT_USER, HKCR, HKCR:, HKEY_CLASSES_ROOT, HKU, HKU:, HKEY_USERS, HKCC, HKCC:, HKEY_CURRENT_CONFIG.
-- `Write()` — writes a value, backing up the previous value for revert. Supports params array for batch writes. Can create missing subkeys.
-- `Read<T>()` — reads with type conversion (supports bool, int, string, string[], byte[], enum). Uses `DoNotExpandEnvironmentNames`.
-- `DeleteValue()` — deletes a value with backup for revert.
-- `CreateSubKey()` — creates a subkey, tracking created intermediate keys for revert cleanup.
-- `DeleteSubKeyTree()` — deletes an entire key tree, backing up all values/subkeys first (max depth 15, max 5000 items).
-- `KeyExists()` — checks if a registry key exists.
-- `CleanupEmptyKeys()` — removes empty keys that were created during apply (sorts by depth, child-first).
-- `Write(params RegistryItem[] items)` and `DeleteValue(params RegistryItem[] items)` — batch variants that deduplicate.
-
-## Service Process Service Details
-- `GetStartupTypeAsync(serviceName)` — reads the configured startup type from the Service Control Manager (`QueryServiceConfig`, plus `QueryServiceConfig2` for the delayed-auto flag). Returns `(ServiceStartupType?, bool NotFound)`; a missing service comes back as `ERROR_SERVICE_DOES_NOT_EXIST` (1060), boot/system starts as `null`.
-- `ChangeServiceStartupTypeAsync(ServiceItem)` — writes through `ChangeServiceConfig`, then `ChangeServiceConfig2` for auto-start targets so a stale delayed-auto flag cannot survive a change back to plain Automatic. Records `ServiceRevertStep` only if the startup type actually changed.
-- `ChangeServiceStartupTypeAsync(params ServiceItem[])` — batch variant for multiple services.
-- `ServiceStartupType` enum: `Automatic`, `AutomaticDelayedStart`, `Manual`, `Disabled`. Note: Boot (0) and System (1) startup types are not used in this app.
-- No child process and no `sc.exe`: handles are opened and closed per operation and Win32 codes are mapped (1060 not found, 5 access denied, anything else reported as a failure).
-
-## Scheduled Task Service Details
-- Uses `Microsoft.Win32.TaskScheduler` library (TaskScheduler NuGet package).
-- `DisableTask(fullPath)` / `EnableTask(fullPath)` — toggle task state with revert step recording.
-- `GetTaskEnabledState(fullPath)` — reads whether a task exists and is enabled; returns `TaskEnabledState` (`Enabled`/`Disabled`/`NotFound`/`Unknown`) and never reports a failed query as "disabled".
-- `DeleteTask(fullPath)` — deletes a task.
-- `GetAllTasks()` — enumerates all tasks recursively with icon extraction via `StartupManagerService.ExtractIcon`.
-- `GetStartupTasks()` — filtered to tasks with LogonTrigger or BootTrigger.
-- `RegisterTask(folderPath, model)` — registers a new task from `ScheduledTaskModel`.
-- `RunTask(fullPath)` / `StopTask(fullPath)` — controls task execution.
-- `GetTaskState(fullPath)` — returns current task state string.
-
-## Revert Step Types
-- `RegistryRevertStep` — actions: `RestorePrevious`, `NoPreviousValue`, `RestoreKey`, `RestoreKeyTree`. Tracks created subkeys for cleanup.
-- `ServiceRevertStep` — stores `ServiceName` and `OriginalStartupType`.
-- `ScheduledTaskRevertStep` — stores `FullPath` and `OriginalEnabled` state.
-- `ShellRevertStep` — stores `ShellType` (CMD/PowerShell) and `Command`.
-- `UsbPowerRevertStep` — stores list of `DeviceState` (InstanceName + Enable) for USB power settings; restoring goes through the in-process `root\wmi` client.
-- `HibernationRevertStep` — stores `WasPresent` (whether the hibernation file existed) and restores it through the power information callback.
-
-## Commit & PR
+- `publish.bat portable|single [--skip-tests] [--no-pause]` — release artifacts; runs the tests first unless skipped.
+- `csharpier format .` / `csharpier check .` — global tool, CI pins 1.3.0. Run it as `csharpier`, never `dotnet csharpier` (that fails as "command not found", which reads like a missing tool). The editor reformats on save, so a touched file may come back with unrelated lines reflowed; that is the formatter, not your edit.
+- Full gate before push: build, test, `csharpier check .`. CI (`.github/workflows/ci.yml`) = restore, Release build, test with `--blame-hang --blame-hang-timeout 30s`, format check.
+
+## Layout
+- `optimizerDuck/` — the WPF app.
+ - `Domain/` — models, contracts, records. No UI dependencies.
+ - `Abstractions/` — `IOptimization`, `IOptimizationCategory`, `ICustomizeSetting`, `ICustomizeCategory`, `IRevertStep`, `RevertContext`, `IWindow`
+ - `Attributes/` — `[Optimization]`, `[OptimizationCategory]`, `[CustomizeSetting]`, `[CustomizeCategory]`
+ - `Conditions/` + `BuiltIn/` — compatibility gating
+ - `Execution/` — `OpCall`, `ChangeSet` + `Change` + `ChangeKind`, `ChangeDetail` + `ChangeDetailCodec`, `OpResult`, `OperationSubject`, `OperationRequest`, `ToolSubjects`, `ChangeRecord`
+ - `Optimizations/Categories/` — Performance, SecurityAndPrivacy, Gpu, PowerManagement, BloatwareAndServices, UserExperience, AI, plus `Debug` (DEBUG-only, excluded from release)
+ - `Optimizations/Models/` — `BaseOptimization`, `ApplyResult`, `OptimizationContext`, `OptimizationResult` and the per-feature item models
+ - `Customize/Categories/` — Desktop, Gaming, Preferences, SystemFeatures
+ - `Customize/Models/` — `BaseCustomizeSetting`, `RegistryToggle`, `RegistryBinding`, `SettingOption`, `CustomizeControlType`, `RecommendationState`
+ - `Revert/` + `Revert/Steps/` — revert data and the persistable steps
+ - `UI/` — UI-facing types only: risk/tag/order enums, `OptimizationState`, `SupportedLanguages`, `ChangeKindPresentation`, `ChangeDetailPresentation`
+ - `Configuration/AppSettings.cs` — settings persisted to `appsettings.json` (`ShellTimeoutMs` default 120000)
+ - `Services/` — business logic: `Conditions/ConditionEvaluator`, `Configuration/{ConfigManager,LanguageManager}`, `Customize/{CustomizeRegistry,CustomizationExecutor}`, `Optimization/{OptimizationRegistry,OptimizationService,OperationRunner,OptimizationValidation}`, `Revert/RevertManager`, `History/ChangeRecordStore`, `System/*`, `System/Primitives/*`, `UI/*`
+ - `UI/` — XAML pages, ViewModels, windows, dialogs, controls, styles
+ - `Common/` — `Helpers/` (`Shared`, `ReflectionHelper`, `CategoryDiscovery`, `WmiHelper`, `UserErrorSurface`, ...), `Converters/`, `Extensions/`
+ - `ApplicationServiceCollectionExtensions.cs` — `AddOptimizerApplication(IConfiguration)`, the whole graph; `App.xaml.cs` only builds the host
+ - `Resources/Languages/` — `Translations.resx` (neutral English) + one file per locale
+- `optimizerDuck.Test/` — xUnit v3, one project, `InternalsVisibleTo`.
+- Data directory `%LocalAppData%\optimizerDuck\`: `Revert/`, `History/`, `Resources/{Downloads,Assets}/`, `Crashes/`, `optimizerDuck.log`, `appsettings.json`.
+- Version lives in `optimizerDuck.csproj` (`<Version>`). Read it there; never hardcode it.
+
+## Adding an optimization or customize setting
+Reflection discovery, no registration array to update.
+- **Optimization**: a **nested class** in the relevant `Domain/Optimizations/Categories/*.cs` file, extending `BaseOptimization`, decorated `[Optimization(Id = "guid", Risk = ..., Tags = ..., Condition = typeof(...)?)]`. That is the only path.
+- **Customize setting**: same nesting in `Domain/Customize/Categories/`, extending `BaseCustomizeSetting`, decorated `[CustomizeSetting(Section = ..., Icon = ..., Recommendation = ..., Condition = typeof(...)?)]`. `Icon` is required (`SymbolRegular`); `Recommendation` is `On` | `Off` | `Depends` | `Experimental` | `None`.
+- **Category class**: `[OptimizationCategory(typeof(PageClass))]` or `[CustomizeCategory(PageType = typeof(PageClass))]`. Category pages auto-register via `AddAllOptimizationPages()` / `AddAllCustomizeCategoryPages()`.
+- **Discovery**: `ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` scans assemblies whose name starts with `optimizerDuck`; `CategoryDiscovery` builds the categories and instantiates their nested items, skipping empty categories. Results are cached. `OptimizationValidation` fails fast on a duplicate or malformed Id during discovery.
+- **Preloading**: `OptimizationRegistry.PreloadOptimizationsAsync()` / `EnsurePreloadedAsync()` and `CustomizeRegistry.PreloadCategoriesAsync()` / `EnsurePreloadedAsync()` run discovery on a background thread; `App.xaml.cs` preloads at startup and the pages await `EnsurePreloadedAsync()` before binding.
+- **DI**: register through `AddOptimizerApplication(configuration)`. The host sets `ValidateOnBuild`/`ValidateScopes`, so a broken or scoped-into-singleton registration fails at startup, not at apply time. Keep it that way.
+- **Results**: an optimization ends `ApplyAsync` with `return context.Changes.ToApplyResult();`. Only an early-out failure constructs `ApplyResult` by hand.
+
+## Execution model
+- `OpCall` is the explicit per-operation context: `Changes`, `Logger`, `CancellationToken`. `OptimizationContext` extends it with `Snapshot`, `StreamService`, `Shell`, `PowerPlans`.
+- Providers record into `call.Changes` and return `OpResult`. Never both throw and record.
+- `ChangeKind` says what a step did: `Change` (modified, carries compensation), `Skip` (already correct), `NotApplicable` (nothing here to act on), `Refused` (Windows refused; not a failure), `Irreversible` (no way back).
+- `DidApplyAnything` = `Change` only, and gates revert persistence. `ModifiedSystem` = `Change` + `Irreversible`, and tells a change from nothing to do. So a run whose only step was irreversible is a success, and a run that recorded nothing is "nothing to do", not a failure.
+- `OperationRunner` is the one lifecycle: run the work, classify the outcome from the recorded steps, write the record, persist revert data when the subject asks for it. `OperationSubject` (Id + Key + English log name) identifies a run and its record; built-in tool ids live in `ToolSubjects`.
+- **Skip policy**: a provider whose mutation needs a privilege it may not have, has a side effect beyond the value it sets, or can be refused on a second call reads the current state first and records a `Skip` when the machine already matches, without calling the mutation (`RegistryService`, `ServiceProcessService`, `ScheduledTaskService`, `PowerPlanChanges`, and the PowerManagement category for hibernation/USB). An item never decides this on its own: a skip recorded at the item level drops the step from the record.
+- **Failure policy**: a provider records a failed `Change` with an error and, when a retry can help, a retry action — it does not throw. Only unrecoverable state throws; the runner turns that into a failed step named for the user. Partial work is persisted with `CancellationToken.None`.
+- **Retry**: `OptimizationService.RetryFailedStepsWithResultsAsync()` (static) re-invokes the stored retry action with a fresh `OpCall` and appends the recovered steps. The optimize page's dialog and `ToolRunPresenter` both call it. Reverting passes a `RevertManager`, a tool passes none, so a retried tool step writes no revert data.
+- **The record**: `OperationRunner` writes `%LocalAppData%\optimizerDuck\History\{id}.json` (one file per subject, atomic, best effort, never part of the revert data). `ChangeRecordStore.TryWrite`/`TryRead` is the only accessor; the details view, the applied badge summary and a retry's attempt counts read it.
+- **Tool actions**: `ToolRunPresenter.RunAsync(OperationRequest)` runs an action under the progress dialog, `ReportAsync` reports it (retry dialog for failed steps, snackbar for a failure with no retry). Every tool page uses it, so an action is run and reported one way.
+
+## Providers
+- `RegistryService`, `ServiceProcessService`, `ScheduledTaskService` — **static**, stateless; call directly.
+- `ShellService` + `ProcessRunner` — DI singletons, reached from optimizations as `context.Shell`.
+- `PowerPlanService` — DI singleton, the only owner of power-**scheme** interop; lean: reads take ids, writes take `ILogger? = null` and record nothing. `PowerPlanChanges` is the single edge that turns those results into `Change` + revert step + retry.
+- `SystemRestoreService` — the only owner of every System Restore WMI call.
+- `RecycleBinService`, `HibernationService`, `UsbPowerService` — static, one Windows operation each (shell Recycle Bin APIs, the documented power information callback, `root\wmi` device power); they fail open instead of throwing. The PowerManagement category records their steps.
+
+## Conditions (compatibility gating)
+- `Domain/Conditions/`: `ICondition`, `ConditionBase`, `ConditionResult`, `ConditionState`, `ConditionValidation`, `WindowsBuilds`, `BuiltIn/` — Windows 10, Windows 11, Windows 11 24H2+, CPU brand, GPU brand, minimum RAM, registry key exists, service exists, Recall installed.
+- Evaluated by the static `Services/Conditions/ConditionEvaluator`. Both `[Optimization]` and `[CustomizeSetting]` accept an optional `Condition = typeof(T)` where `T : ICondition` with a public parameterless constructor.
+- `ConditionResult.Available` / `.Unsupported(title, description)` / `.Error()`. Note the two providers are *factory* delegates (`() => Loc.Instance[...]`), so text is localized lazily. `Error` and an unknown `SystemInfo` **fail open** (never hide).
+- Only `Unsupported` blocks, and only when the item is neither applied nor hidden by the user. `ConditionValidation.Validate(...)` fails fast on misconfigured metadata.
+
+## Revert system
+- One JSON file per subject: `%LocalAppData%\optimizerDuck\Revert\{id}.json`. Applied state is inferred from file presence.
+- `RevertManager` is the API: `SaveRevertDataAsync`, `RevertAsync`, `AppendRevertStepAsync`, `RemoveRevertStepAtIndexAsync`, `RemoveRevertStepsAtIndexesAsync`, `RemoveRevertData`, plus static `IsAppliedAsync`, `GetRevertDataAsync`, `ClearAllRevertData`, `RemoveOrphanedTempFiles`.
+- **Atomic writes**: temp file via `FileStream(WriteThrough)` + `Flush(flushToDisk: true)`, then `File.Replace`. Stale `.tmp` files are swept at startup.
+- **Concurrency**: a per-file `SemaphoreSlim` (30 s timeout) in `RevertManager.FileLocks`. A lock entry is never disposed while another thread holds or waits on it.
+- **Compact layout**: only successful steps persist, re-indexed with no gaps. Re-apply appends; a recovered retry step appends (never overwrites), so LIFO revert still ends at the original backup.
+- **Step registry**: `_stepRegistry` is a lazily built name → `Func<JObject, IRevertStep>` map; a new step auto-registers by implementing `IRevertStep` with a public static `FromData(JObject)`. Persisted data with an unknown type becomes a failing step with a clear message, never a silent skip.
+- **Steps** (`Domain/Revert/Steps/`): `RegistryRevertStep`, `ServiceRevertStep`, `ScheduledTaskRevertStep`, `ShellRevertStep`, `UsbPowerRevertStep`, `PowerPlanRevertStep`, `PowerSettingRevertStep`, `HibernationRevertStep`. Each verifies its own effect in `ExecuteAsync` (read-back, re-query, re-check, re-read). Access denied is failure, never success; missing required state throws (fail closed).
+- `IRevertStep.ExecuteAsync(RevertContext, ILogger)`: `RevertContext` carries `Shell`, `PowerPlans` and the logger, so undo runs through the same DI services and the configured shell timeout.
+- `RegistryRevertStep` actions: `RestorePrevious`, `NoPreviousValue`, `RestoreKey`, `RestoreKeyTree`; it tracks the subkeys it created so cleanup can remove them.
+
+## Customize setting API
+- `RegistryToggle` takes `OnValues` / `OffValues` (lists; `null` entry = key absent), `DefaultValue`, `IsOptional`, `ValueKind`. There is no `OnValue` / `OffValue` / `TreatMissingAsDefault`.
+- Dropdown settings override `ControlType => CustomizeControlType.Dropdown` and `GetOptions()` returning `SettingOption`s built with `Option(key, regPath, regName, value)` or `Option(key, value, params RegistryBinding[])`. The base class auto-reads and auto-writes through the bindings and shows a "Custom" / "Not set" fallback for values outside the options.
+- When you override `ApplyAsync`, call `await ExecutePostActionAsync()` yourself (it is guarded by `NeedsPostAction`).
+- Setting writes go through `CustomizationExecutor.ApplyWithDebounceAsync(value, applyAction, debounceMs = 400)`: it debounces, then runs one queued apply at a time, so a burst of toggles applies only the last value. `CustomizeItemViewModel` is the caller.
+
+## Localization
+- `Domain/UI/SupportedLanguages.cs` is the single source of truth for the language list (17 entries, currently `en-US` … `id-ID`); the UI binds `SupportedLanguages.All`. A language exists only when its `Resources/Languages/Translations.{culture}.resx` also exists, and `LanguageManagerTests.EveryNeutralKey_ResolvesInEverySupportedLanguage` enforces that every neutral key resolves in every locale. Do not hardcode a language list anywhere else.
+- `Translations.resx` (English) is the key source. Preserve `{0}` placeholders verbatim and in order, escape XML specials, keep `xml:space="preserve"`.
+- Goal is natural localization, not word-for-word translation; each locale must read as if written by a native speaker who knows Windows, PC hardware and optimization software.
+- Keep technical terms in English where that locale's users expect it (e.g. Vietnamese: SSD, HDD, RAM, CPU, GPU, Driver, Registry, BIOS, UEFI, PowerShell — never "Trình điều khiển" for Driver), and translate the concepts with a natural localized equivalent where one exists (e.g. vi "Memory Integrity" → "Tính toàn vẹn bộ nhớ"). Decide per locale; conventions differ per language.
+- Never copy English sentence structure that sounds wrong in the target language, and never pad to match the source length. No em dashes in any locale — restructure with commas, periods, colons or parentheses natural to the language.
+- Consistency order: correct meaning, then natural language, then established terminology, then cross-app consistency. The same source term may need different wording per context ("Startup" as manager vs. at startup).
+
+## Tests (xUnit v3, integration style)
+- **No mocking libraries.** Test doubles are hand-written (`StubOptimization`, `TestShell`, `TestRunner`, `EveryOperationDetail`, ...) implementing the real interfaces.
+- **Real I/O**: real filesystem (revert JSON), real registry under `HKCU\Software\TestOptimizerDuck*`, real CMD/PowerShell processes.
+- **STA**: a WPF-touching test uses a `private static RunInStaThreadAsync` helper (STA thread + `TaskCompletionSource`). There is no shared helper — the test class defines its own, so copy the existing one when a new class needs it.
+- **Logging**: `NullLogger<T>.Instance` / `NullLoggerFactory.Instance`.
+- **Naming**: `{Method}_{Scenario}_{ExpectedResult}`, e.g. `ApplyAsync_Success_PersistsRevertDataFile`.
+- **Cleanup**: `try/finally` or `IDisposable` (`AppDataCleanupFixture`); a test that writes revert data removes both `{id}.json` and `{id}.json.tmp`.
+- No coverage gate — cover the changed logic meaningfully, and add or update tests for what you change even when nobody asked.
+- CI runs with `--blame-hang --blame-hang-timeout 30s`: no test may hang longer than 30 s.
+
+## Style
+- Nullable enabled, file-scoped namespaces, implicit usings. 4-space indent, max line length 100.
+- PascalCase types and members, `_camelCase` private fields, `camelCase` locals and parameters.
+- Comments are sparse in this codebase; do not add unnecessary ones.
+- DI and MVVM via `Microsoft.Extensions.Hosting` + `CommunityToolkit.Mvvm`; pages and ViewModels are singletons.
+- `WmiHelper.Initialize()` registers WMI cleanup for abnormal termination; keep the call on the startup path.
+- Environment: `net10.0-windows`, WPF, `WPF-UI` + `WPF-UI.DependencyInjection` 4.3.0, `CommunityToolkit.Mvvm` 8.4.2, `Microsoft.Extensions.*` 10.0.10, `Newtonsoft.Json` 13.0.4, `Serilog` 4.4.0 (+ `Serilog.Extensions.Hosting` 10.0.0, `Serilog.Sinks.File` 7.0.0), `System.Management.Automation` 7.6.4, `TaskScheduler` 2.12.2. Tests: `xunit.v3` 3.2.2, `xunit.runner.visualstudio` 3.1.5, `Microsoft.NET.Test.Sdk` 18.8.1, `coverlet.collector` 10.0.1. Versions live in the two csproj files — check there rather than trusting this list.
+
+## Commits and PRs
- Conventional Commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `i18n:`, `chore:`.
- Branch from `master`: `feature/<name>` or `fix/<issue-id>`.
-- PRs: clear description, linked issue (`Closes #123`), passing CI (build + test), screenshot for UI changes.
-- Never commit secrets or machine-specific paths.
-- Run `csharpier format .` before committing.
-- Verify with: `dotnet build`, `dotnet test`, `csharpier format .` before push.
+- Run `csharpier format .`, then build and test, before committing. Never commit secrets or machine-specific paths.
+- PR: clear description, linked issue (`Closes #123`), passing CI, screenshot for UI changes.
<!-- rtk-instructions v2 -->
# RTK — Always Prefix Shell Commands with `rtk`