Free, open-source Windows optimization tool for performance, privacy, and simplicity.
C# csharpdebloatdotnetgamingopen-sourceoptimizationoptimizeroptimizerduckperformanceprivacytweakertweakswindowswinui
docs: rewrite AGENTS.md as a condensed, current guide
fatDuck9df4835b5157
diff --git a/AGENTS.md b/AGENTS.mdindex 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`