* docs(win11creator): correct architecture and guide
Update documentation to match actual Win11 Creator implementation:
- Clarify customizations run at first logon via autounattend.xml rather
than offline WIM modification
- Correct removed bloat AppX count from 40+ to 19 packages
- Update USB partition layout to single FAT32 partition with WIM split
- Clarify OneDrive uninstall timing during first logon
- Document missing helpers including USB functions and oscdimg helpers
- Document edition pinning, $OEM$ fallback scripts, and WIM metadata validation
- Update logging location and remove offline registry tweak wording
* docs(win11creator): clarify timing and media limits
Toggles are identified by name prefix, not by the Type field, so the
WPFTweaks-prefixed key made Reset-WPFCheckBoxes treat this entry as an
ordinary checkbox and force it off on every tab build, deleting the
NoLockScreen value it had just set.
Closes#5060
* chore(dns): remove Mullvad DNS providers
Mullvad is shutting down its public encrypted DNS servers and sponsoring
Quad9 instead, so the six Mullvad profiles would resolve nothing once the
servers go dark.
Drops the Mullvad entries from config/dns.json, trims them out of the
WPFchangedns ComboItems, and removes the matching bullets and the
DoH-fallback note from the tweaks guide. Quad9 already ships as a provider,
so users have a documented destination.
The generated code-reference page for this tweak is left alone; the
pre-release workflow regenerates it from config/tweaks.json.
* test(dns): use generic fixtures for DoH-only providers
The DoH-only and SecondaryDohTemplate paths in Set-WinUtilDNS were covered
by fixtures named after Mullvad and carrying its real resolver addresses.
Those code paths still exist, so the coverage stays; only the naming was
tied to a provider WinUtil no longer ships.
Renames the fixtures to DohOnlyProvider and DohOnlyNoSecondary and swaps in
RFC 5737 / RFC 3849 documentation addresses and example.com templates, so
the tests no longer read as if they exercise a shipped provider.
* Rework the Win11 Creator tab into a three step wizard
- Turn the stacked sections into pages you can navigate between
- Move the edition picker and driver option to the modify step
- Show a working page while mounting and modifying run
- Show what the run changes and a finished panel with the output path
- Put the status log in its own card next to the steps
- Rename Clean & Reset to Start Over and move it below the actions
* Follow the existing colours on the Win11 Creator tab
- Take button text and icon colour from the button they sit in
- Stop the implicit TextBlock style painting a label background on buttons
- Colour step headers from the tab item state
- Use the label accent for headings and field labels like the other tabs
* Cut repeated markup on the Win11 Creator tab
- Render button icon and label from a ContentTemplate, glyph goes in Tag
- Render the step header from a HeaderTemplate the same way
- Move the page scroll wrapper into the tab control template
- Derive the text styles from one another instead of repeating setters
* fix: tidy the dropdown and stop the spinner stuttering
- combo box items painted their own background while the popup painted
another, so the list read as loose labels on a mismatched sheet; items are
transparent now and the popup carries the colour
- stretch the item presenter so a highlight spans the popup instead of just
the text, and bind the popup width to the closed box
- cache the working page's spinner: it animates a rotation on a TextBlock,
which re-rasterises the glyph every frame on the interface thread
- run that animation only while the page is visible; it was started on Loaded
and never stopped, so it kept spinning after the step was done
* Stop the Win11 Creator status log rendering justified
The shared TextBox style sets HorizontalContentAlignment to Stretch, which
WPF reads as TextAlignment.Justify. Every other box in WinUtil is single
line, so the status log is the only place it shows, and there it stretched
each wrapped line to the full width with gaps between the words.
Left-aligns it, and while the log is being read as a log rather than as
prose: monospace from a new Win11LogFontFamily theme key so the timestamps
form a column and a wrapped line is visibly not a new entry, and no effect,
since the shared style's drop shadow has neither border nor background to
sit under on this control and smeared the glyphs instead.
* Show the working page for export, USB write and Start Over
Only mount and modify moved to the working page. Saving an ISO, writing a
USB drive and Start Over all ran with the finished output page still on
screen, so the three longest operations in the tab were the ones that looked
like nothing was happening.
All three now open the working page for their duration and return to the
page they belong on: the output step for the two that produce media, the ISO
picker for Start Over, which has just deleted the working directory. Failures
leave the working page before their message box rather than putting a modal
over a spinner, and a finally guard covers cancellation, which skips catch.
Start Over spins the icon backwards. Its work undoes rather than produces,
and reading that off the animation is quicker than reading the label.
* cut comments
Leaves the four that answer a "why is it written this way" a reader cannot
get from the code: the shared TextBox style's justify and drop shadow, the
spinner tag being set before the page is shown, going back to Select rather
than Modify after a failed modification, and the finally guards existing for
cancellation rather than for failure.
* cut changes that only reword
Reverts three edits that changed wording without changing meaning, and drops
the comment on the failed-modification branch.
* cut comments that narrate the code
* address coderabbit review
Hyphenate three-step, and let the chevrons grow past their minimum instead of
pinning a size the glyph could outgrow.
* dismount a replaced ISO and name the USB disk when done
Picking a second ISO after verifying one left the first attached: the mount job
clears Win11ISOImagePath, which is the only handle cleanup has to it. Dismount
it in the job, off the interface thread, before that reset.
The done panel now names the disk it wrote, the way the ISO branch names its file.
* keep the wizard inside the card at the minimum window width
The step column and the chevron grid's middle column were both pinned at 620,
while the left card is about 485px at the 800px minimum. The pages do not
scroll sideways, so controls past the card edge were unreachable.
Both are now capped rather than fixed, and the removed WPFWin11ISOArchLabel was
never assigned by anything.
* stop a replacement mount when the old ISO will not dismount
The warn-and-continue path cleared Win11ISOImagePath anyway, which strands the
old mount for the rest of the session - the leak the dismount was added to
close. It now reports and throws instead, from inside the try so the finally
still re-enables the browse and mount buttons.
* cut comments that narrate the code
* drop the OneDrive sync claim from the modify step list
The post-install script sets DisableFileSyncNGSC=1, but it is prepended to
FirstLogon.ps1, whose own body then sets the same value back to 0. The policy
never survives, so the bullet was promising something the run does not do.
Replaced with search box suggestions, which it does do.
* Add a job layer for long running work
- Start-WinUtilJob owns busy state, progress, taskbar, logging and errors
- Write-WinUtilJobProgress reports from a job without UI checks in the body
- Post UI updates instead of waiting on the dispatcher for each one
- Move Invoke-WPFInstall onto it as the first workflow
* Move the remaining app and feature workflows onto the job layer
- Uninstall, AppX install, Features, OOSU and installed detection
- Drop the per workflow busy flag, progress, taskbar and error handling
- Rework their tests to check the job and its body instead of runspace internals
* Run the WinUtil interface on its own thread
main.ps1 now only manages the run: it creates a dedicated STA runspace for
the window, waits for it, and reports whatever the interface thread failed
with. The interface itself moved into Start-WinUtilUserInterface, so the
thread that owns the window does nothing but paint and dispatch.
- New-WinUtilSessionState builds one starting point for both the interface
runspace and the worker pool, carrying $sync, the compiled script globals
and every WinUtil function. The pool previously copied only functions
matching winutil|WPF, which is not enough for a runspace that has to build
a tab.
- Invoke-WPFUIThread hands work to the interface runspace as body text plus
parameters instead of marshalling a scriptblock. A scriptblock keeps the
session state it was written in; running one across runspaces loses the
caller's variables on an async post and costs roughly twenty times as much
per command, which turned a checkbox refresh into a multi-minute freeze.
- Both helpers stop at a shut-down dispatcher, so a job that outlives the
window finishes quietly.
* Move every long workflow onto the job layer
Tweaks, undo, AppX removal and the five Win11 Creator workflows now go
through Start-WinUtilJob like the install workflows already did. That
removes the five hand-built STA runspaces and the function-definition
injection the ISO code needed to reach its own helpers.
- One busy flag: $sync.ActiveJob replaces ProcessRunning and
Win11ISOProcessRunning, and only the job layer writes it.
- Write-WinUtilJobProgress -Hide absorbs the last use of
Set-WinUtilTweaksProgressIndicator, so the progress bar and taskbar item
have a single owner. The helper is gone.
- Show-WinUtilMessage marshals onto the interface thread and logs the
prompt, so a job body can ask a question without knowing which thread it
is on. The raw MessageBox calls in the ISO workflows are gone.
- Win11 Creator status-log lines also go to the session log, and the
per-workflow Log/SetProgress helpers are gone.
- Get-WinUtilOscdimgPath and Get-WinUtilFreeDriveLetter are now real
functions rather than nested ones, so the pool can resolve them.
* Log from every WinUtil thread into one session file
Start-Transcript only records the runspace it was started on, so every line
a worker or the interface logged was being dropped. Write-WinUtilLog now
appends to the session log directly, serialized with a named mutex, and the
console transcript gets its own file in the same logs directory.
* Document the threading model and the job layer
* Stop Invoke-WPFUIThread leaking the body's output to its caller
The helper returned whatever the body produced, including a bare $null. Callers written
against the old void signature then returned an array instead of their own value:
Get-WinUtilSelectedPackages handed back @($null, $split), both package lists read as empty,
and Install and Uninstall reported success without installing or removing anything.
Output is now suppressed unless -PassThru is asked for, which only Show-WinUtilMessage needs.
Covered by tests on both the helper and the package split.
* Put every button that changes the system on the job layer
Invoke-WPFButton now classifies the press instead of running it. Anything that changes the
system gets a job; tab switches, selection helpers, window chrome and the WPFPanel* applet
launchers stay on the interface thread. Updates, the Ultimate Performance plan, the Fixes
buttons, OpenSSH Server, the system repair scan and the AppX query previously ran inline,
which froze the window, produced no progress and interleaved their output with a running job.
The job layer also owns the console banner now. Write-WinUtilJobBanner draws it once, so the
eleven hand-drawn === boxes are gone and every operation announces its start, not only its end.
- The job is named after what the button says, read from the config or the control itself,
so there is no second list of labels to keep in step.
- Show-WinUtilMessage replaces the last raw MessageBox calls, which could not have worked
from a worker thread.
- Write-WinUtilJobProgress replaces the last direct Set-WinUtilTaskbaritem calls.
* Document button routing and the job banner
* Read function bodies from the FunctionInfo instead of the function provider
Building the session state is on the path to first paint, and going through
function:\ for every function cost about as much as the whole interface
runspace saved. Time to first window is back level with upstream.
* Render the taskbar overlays after first paint
The logo overlay render costs about 55ms and nothing can see it until the window
is up, so it no longer sits between the interface being built and being shown.
Both the logo and the status overlays are now rendered from the same deferred
call once the window has painted.
* Make a failed package fail the job
Both package helpers ran the manager and moved on regardless of its exit code, so
a run in which nothing installed still reported success with a green checkmark.
They now emit a result per package, classified from the exit code: succeeded,
skipped for WinGet telling us there was nothing to do, or failed. The workflow
collects them and Complete-WinUtilPackageRun prints the summary and throws when
anything failed, which is what puts the job into its failed state.
* Time every pipeline step and report the slowest ones
Measure-WinUtilStep wraps a step, passes its output through untouched, logs how
long it took and keeps the record. Every job and the interface build end with a
summary ranking the slowest steps and their share of the total, so "which tweak
is taking forever" and "what is holding up startup" are answerable from the log
instead of by guessing.
Wired into the interface build, each tweak, each undo, each feature, and each
package. Jobs also log their own wall-clock duration, and the interface logs the
moment it can first service input.
* Render the taskbar overlays on the main thread's runspace
The overlays need an STA thread, which the worker pool is not, so they get one of
their own. Starting it from the interface thread cost more than it saved: opening
the runspace took 154-221ms there against 88ms of rendering. Starting it from the
main thread instead is free, because that thread does nothing but wait for the
window, and the render then overlaps the interface build.
Measured over three runs each, time from start to the interface accepting input:
2071/2105ms before, 2105/2131/2193ms started from the interface thread,
2026/2044/2050ms started from the main thread.
Also caches the session state, which two runspaces now share, and moves the
runspace cleanup registration into its own function for the second caller.
* Cut startup to first interaction roughly in half
- wire button clicks by type name against a HashSet, not a pipeline per $sync key: 335ms to 81ms
- build no tab content before first paint; Invoke-WPFTab already builds the tab it activates
- group apps by category into Lists, not by appending to arrays
- interface built ~1460ms to ~465ms, ready for input ~2090ms to ~858ms
* Warm the unopened tabs while the interface is idle
- queue each remaining tab at ApplicationIdle priority after first paint
- one tab per queued operation so input is serviced in between
- first click on a tab no longer pays for its build
* Report failures with the context needed to act on them
- Write-WinUtilErrorRecord logs message, exception type, command, line and script stack
- used by the job layer, the button funnel, the interface dispatcher and the main thread
- route buttons to the job layer by whitelist, so chrome and popup toggles stop starting empty jobs
* Wire the Install tab controls where they are created
- ChocoRadioButton, WingetRadioButton and the install action buttons come from
appnavigation.json, so they do not exist until the Install tab is built
- the interface build wired them anyway, which is the three null-reference errors
reported on close since tab content moved behind first paint
- Initialize-WinUtilInstallTabControls now does it from the tab build, guarded
- offline mode disables the install buttons from there too, for the same reason
- new test fails if the interface build touches any config-generated control
* Stop losing warnings and non-terminating errors from job bodies
- a worker buffers its warning and error streams on an object nobody reads:
Write-Warning never reached the log, Write-Error reached nothing at all
- the job layer merges both into the log, so all 30+ Write-Warning and 4
Write-Error sites in the helpers are visible without touching each one
- the interface runspace warning stream is drained on exit too
- $sync.LoggedErrors counts error events, detail lines excluded
- a job that logged errors without throwing now finishes as "N error(s)"
with a warning overlay instead of a green checkmark
* Drive winget through Microsoft.WinGet.Client for real progress
The winget CLI hides its progress bar as soon as its output is redirected, so a
package could only ever be reported as started and finished. The module reports
progress and returns a structured result.
- Install-WinUtilWinGetClient installs and imports the module, cached per session
- Invoke-WinUtilWinGetCommand runs a cmdlet on a nested PowerShell and polls its
progress stream, which cannot be redirected like output or errors
- percentages map into the package's slice of the job bar: "7zip.7zip - 1.9 MB / 1.9 MB"
- outcome comes from Status and InstallerErrorCode, not an exit code
- a package already present is upgraded, not reinstalled: Install-WinGetPackage
re-downloads and re-runs the installer even without -Force
- detection uses Get-WinGetPackage and matches on name as well as id, so apps
installed outside winget are recognised (Brave, and every other ARP entry)
- falls back to the command line unchanged when the module cannot be installed
Verified against real winget in the eval VM, 12 checks; 545 unit tests pass.
* Show the install phase as running instead of finished
Measured what the module actually emits: 7 progress records whether the package
is 1.9 MB or 57.8 MB, only two of them download samples, and the install phase
reports 0 then 100 with nothing between. On VLC the install is 4.3s of the 9.7s.
- the download gets the first half of the package's slice, so reaching 100%
download no longer fills the bar
- the install phase pulses the bar and counts elapsed seconds in the label,
because neither winget nor the module exposes installer progress
- scan the whole progress collection, not just its last record: a byte sample
can be superseded within milliseconds
- RoundedProgressBarStyle gained an indeterminate trigger; it had none
Fixes uninstall reporting a package that is not installed as a failure, which is
what UninstallError after 354ms was, and adds ExtendedErrorCode to the detail.
* Say what a winget failure actually was
The command line prints a sentence for a failure; the client module returns only
an HRESULT, so the same failure read as "COMException (0x8A15007D)". Both report
the same number, so one table serves both paths.
- Get-WinUtilWinGetErrorMessage explains the codes WinUtil hits, and gives the
hex plus the return-code reference for anything else
- 0x8A15007D now reads: installed for a single user, cannot be removed while
running as administrator, remove it from Settings > Apps
- unsigned HRESULTs are wrapped rather than cast, which overflowed Int32
- a shared failure reason is repeated in the thrown message
- the banner wraps at 76 columns instead of drawing a box wider than the console
* Keep the run position in the progress text during a package
- the bar itself was already whole-workflow: 0-12, 25-37, 50-62, 75-87, 100
- but the status read "A.A - 50% downloaded", dropping the (n/total) the old
per-package messages carried
- callers pass a label, so it now reads "A.A (1/4) - 50% downloaded"
* Pulse the progress bar in place instead of filling it
- IsIndeterminate makes WPF discard Value and stretch the indicator across the
whole track: measured 398px of a 400px track at value 40, against 159px correct
- the pulse is driven by Tag instead, so the bar keeps the progress it reached
- RemoveStoryboard on exit, because Stop left the indicator at whatever opacity
the pulse happened to be on
* perf: cut Install tab build and keep the interface answering during warmup
- look apps up by hashtable index, not dynamic member: Install tab app area 361ms -> 91ms
- cap a render pass at 25 apps so a large category cannot stall the interface
- yield between batches when building speculative tab content
- claim a tab as initialized before building it, so a click during a yield cannot double build
- time each step of a tab switch
* xaml: drop layout elements and styles that do nothing
- remove 8 single child wrappers from control templates, one per instance of every button, toggle and tweak switch
- delete unreferenced labelfortweaks and ScrollVisibilityRectangle styles
- verified pixel identical across all five tabs
* fix: bring the last workflows into the job layer
- upgrade all runs package by package on the worker instead of spawning a console
- PS profile setup runs pwsh with output captured, not a Windows Terminal tab
- resolve the PS7 profile path from pwsh, so remove targets the file install wrote
- treat winget exit 3010 and 1641 as success; a reboot requirement is not a failure
- drop the power plan success popups, the job layer already reports the result
- load PresentationFramework before a message box on a worker, and log if it cannot show
- probe optional commands with -ErrorAction so a missing choco does not throw
- refresh PATH after installing chocolatey
* fix: keep the runspace handle out of the console and the pipeline
- suppress the IAsyncResult Start-WinUtilJob got back, which printed a table on every button press
- test fails if any caller leaves Invoke-WPFRunspace unassigned
* fix: choco parity with winget, and prompts that cannot hang or assume consent
- choco runs one package per call, so progress moves and a failure names the package
- add an Upgrade action; upgrade all was building "choco install all", which is not a package
- explain a choco failure from its own output instead of reporting a bare exit code
- pass a progress slice to choco from install and uninstall, as winget already gets
- never show a message box without a window: a modal there never returns
- an unanswerable prompt answers No, so it can never stand in for consent
- uninstall requires an explicit Yes rather than the absence of a No
* feat: headless runs report and finish on their own
- progress goes to the console when there is no window, throttled so downloads do not bury it
- one entry point for preset and config; a preset can now be a baseline a config adds to
- apply selected toggles, which only ever applied themselves from the window
- exit code carries the outcome: 0 clean, 1 problems, 2 nothing selected
- elevation waits for the elevated run and hands its code back
- per step timeout, so an installer that never returns cannot hang the run for good
- a step that throws no longer abandons the remaining steps
- name an unrecognised config entry instead of failing on a null list, and ignore duplicates
- import with no window logs instead of throwing on a message box type it cannot load
- temp file cleanup skips files in use rather than reporting each as an error
* perf: stop the interface stalling while the app list loads
Measured with a new input-priority heartbeat: 2669 ms unresponsive across 18
stalls, worst 399 ms. Now 502 ms across 5, worst 151 ms, and nothing after the
first three seconds.
- cache app icons on disk and fetch the missing ones on a worker; assigning a
remote address to an Image made WPF fetch and decode it, landing back on the
interface thread whenever the network answered, for a minute after startup
- share the six app entry event handlers instead of building them per entry:
3.18 ms to 1.36 ms per entry, measured
- slice rendering and tab building by a deadline rather than an entry count, so
a slower machine cannot turn a batch into a stall
- yield while building the tab opened at startup, as the warmup already did
- reject a ParameterList that is a flattened pair; it silently ran the worker
with two characters of the parameter name and did nothing
- add Start-WinUtilUIHeartbeat behind WINUTIL_TRACE_UI to measure any of this
* fix: build the other tabs before finishing the app list
Tab warmup was queued at idle priority while app rendering was queued at
background priority, so no tab was warmed until every render pass had run.
For the first few seconds every tab except the open one was empty, and
clicking one paid for its whole build: Tweaks measures 400-530 ms.
Verified from the log: all tabs were ready after 32 of 32 background steps
before, and after 5 of 32 now.
- warm tabs at background priority so they are not starved by the app list
- hold app rendering while any tab is still unbuilt
- stand aside for 400 ms after input, and skip drawing entries for a tab that
is not on screen, resuming when it is
- report the whole latency distribution rather than only gaps over 60 ms; a
thread kept busy by short pieces of work showed no stall while every
interaction still waited behind the piece in flight
* fix: ask before closing over running work, and shut down in order
Closing while a job ran tore the worker pool down underneath it. A queued
instance then started on a runspace already in Closing, threw on a thread
pool thread where nothing catches, and ended the process with an unhandled
InvalidRunspaceStateException instead of exiting.
- ask whether to wait for the running job or stop it, and keep the window
open if the close is cancelled
- track what is running so it can be stopped, and stop it before closing the
pool rather than pulling the runspaces away from it
- refuse to queue new work once shutdown has begun
- close the window by itself once an awaited job finishes
- bound the wait, so a worker that cannot be stopped does not keep the window
open for ever
- phrase the question so the buttons answer it in any language; Windows labels
them itself and text naming them Yes and No does not match Ja and Nein
- treat a missing collection as empty; @($null) is a one element array, which
read as one running item when nothing was running
* fix: let a running job finish in the console after the window is closed
Waiting kept the window open until the job ended, which is not what closing
it means. The window now goes at once and the run continues where it can
still be seen, ending the process when it is done.
- close the window immediately and leave the job on the worker pool
- skip the pool shutdown on that path; it would stop the work just kept
- wait for the job on the main thread, then close the pool and exit
- treat a shut down dispatcher as no window, so progress reaches the console
instead of being posted to a dispatcher that drops it
- bound that wait, so a job that never returns cannot hold the process open
- guard the close post against a window that has already gone
* feat: pause button, and progress that rewrites its line
- add a pause button beside the progress bar; a run holds at the point every
loop reports progress, since a command already started cannot be suspended
- hold only inside a job worker: whoever presses pause reports it through the
same progress call and would otherwise wait on itself
- clear the pause once the body returns, or the finish reporting pauses too and
the job stays marked running for ever
- release it when the window is closed over the job, since there is then no
button left to resume with
- rewrite the console progress line in place rather than adding one line per
update; a single install scrolled a screenful
- keep one line per update when output is redirected, where there is no cursor
to move, and throttle harder there
- say goodbye where the process actually ends; closing can be declined or leave
a job running
* feat: stop button for the running action
- add a stop button beside pause; it asks first, since stopping an install
halfway is not undoable
- end the run at the same safe point a pause holds at, so anything already
started finishes and nothing is cut in half
- report it as stopped rather than failed, through its own cancellation
- clear the stop before reporting it, or the report throws it again from inside
the handler doing the reporting
- release a pause when stopping, or the run would never reach the point where
it notices
- cut the worker off after a grace period, since a single long step reaches no
safe point until it returns
- reset both flags per job, so a late stop cannot end the next run
* fix: use a stop glyph that does not look like a missing one
U+E71A is a hollow square at button size and reads as the empty box a font
shows for a code point it lacks. U+E73B is the filled square.
- add a test that every private use code point in the markup and the scripts
exists in Segoe MDL2 Assets
* fix: icon buttons render in the icon font, not a fallback
A char assigned to Content is not laid out with the control's own font. It
falls back to whatever font claims the code point and is drawn in that font's
colour and metrics, which is why the pause icon came out teal and a different
size from the cross beside it. Add-SelectedAppsMenuItem already cast to string
for the same reason.
- cast every icon assignment to string: pause, play, the app entry popup and
the theme button
- use the cancel cross for stop; a square is a blank block at button size
whether it is filled or hollow
- test that no icon reaches Content as a char
* fix: the font scaling slider goes where it is clicked
WPF leaves IsMoveToPointEnabled off, so a click on the track pages by
LargeChange instead of moving the thumb to the pointer. LargeChange defaults
to 1.0, which over a range of 0.75 to 2.0 is most of the track, so clicking
anywhere toggled between 100% and 200%.
- follow the click, and page by one tick rather than a full unit
- test that every slider does both
* fix: draw the logo at the size it is asked for, and give the window its own icon
The rasteriser built the bitmap from the canvas rather than the requested
size, so every render came out 100 by 100 whatever was asked for: a 32px icon
was that downscaled, and anything larger was an upscale. The canvas was also
smaller than the artwork, whose paths run to about 108 by 110, so the right
and bottom edges were cut off. Between the two, the logo covered about a third
of the icon it was drawn into.
- rasterise from the geometry's real bounds into a bitmap of the requested
size, centred and filling the frame
- keep the shapes in one place, so the control and the bitmap draw the same art
- set the window icon at the sizes the system reports for this display, small
and large, instead of leaving Windows to scale one bitmap
- hold the icon handles for the life of the window and free the ones replaced
* fix: give the nav logo its square box back
Fitting the box to the artwork left no room around it. The logo is taller than
it is wide, so a square control filled by it edge to edge sat against the tab
buttons next to it.
- centre the artwork in a square box with a small margin, so the control fills
the size it was given rather than the artwork's own proportions
- the bitmap form is unchanged and still fills the frame, which is what an icon
wants
* refactor: one background queue, one UI-alive check, drop the stall tracer
- move the DPI window icon work out to feat/dpi-window-icon and revert it here
- drop Start-WinUtilUIHeartbeat: it found the startup stalls, it is not
something a normal run should carry
- add Start-WinUtilBackgroundQueue and put tab warmup and app-entry rendering
on it; they were the same pump written twice
- add Test-WinUtilUIAlive, replacing the same dispatcher guard hand-written
eleven times in three spellings
- carry the queue name as the dispatcher's own argument, not a captured
variable, so the posted step still resolves where it was written
- give Invoke-WinUtilWhenIdle an -Argument for the same reason
- load the WPF assemblies in preferences-theme tests instead of relying on
logo-render having loaded them first
* docs: bring the agent rules in line with the job layer
Section 13 still pointed at Set-WinUtilTweaksProgressIndicator, which the job
layer removed, and said nothing about the pieces that replaced it.
- point the UI-helper rule at Write-WinUtilJobProgress and Test-WinUtilUIAlive
instead of the deleted progress indicator
- say that long operations go through Start-WinUtilJob, and that a job body
owns neither the busy flag, the banner, nor its own interface handling
- send deferred interface work through Start-WinUtilBackgroundQueue rather
than a fourth hand-rolled pump
- record how values reach a posted scriptblock, and why a closure is the wrong
answer: it carries the value but binds command lookup to a copied scope
- state that diagnostic scaffolding is measured with and then deleted
- require each Pester file to load what it needs; several passed only because
an earlier file in alphabetical order had loaded it
* refactor: trim the package work back to what the pipeline needs
The winget client module earns its place: winget.exe hides its progress bar
once its output is redirected, so the CLI can never say how far along an
install is and the progress bar has nothing to show. What rode in behind it
did not.
- keep the module, the per-package progress and the result objects both
managers now return; those are what the job layer reports from
- take the action from the caller instead of probing the machine first:
Install, Uninstall and Upgrade each pick their own cmdlet and verb, matching
the set Install-WinUtilProgramChoco already takes
- drop the Get-WinGetPackage probe with it, which cost a nested call per
package and made the module path mean "install or upgrade" while the command
line path still meant "install"
- send the upgrade workflow through -Action Upgrade, which is what it was
always asking for
- revert Invoke-WinUtilCurrentSystem to the command line; reading which apps
are installed has nothing to do with reporting progress
- cut the winget and choco error tables: the hex code and Microsoft's own list
say the same thing without a copy to keep in step, and choco's reason is
already in the output that gets logged
* test: drop the tests that assert on source text
Sixty-six tests read a function file and regex-matched its contents, so they
failed on edits that changed no behaviour: ten of them broke during a refactor
that only moved code between files. A test that pins how something is spelled
is an edit detector, not a test.
- remove the It blocks that Get-Content a .ps1 and match against it, and the
Describe blocks left with nothing in them
- keep the ones that read source to check a set rather than a spelling, such as
every WPF handler resolving to a defined function and every $sync member
being declared; those catch a real mistake
- drop Get-WinUtilFunctionFile, which had no callers left
* fix: make the active job slot safe to claim and release
Three defects in the job layer's shared state, all of them races that the
dispatcher happened to hide.
- claim $sync.ActiveJob under the collection's own lock. Interface events are
serialised by the dispatcher, but a headless run, a scheduled caller and a
job body starting another job are not, and a test-then-assign there let two
jobs both believe they owned the slot
- identify a run by token rather than by name. A worker the stop watchdog cut
off can still be unwinding when the next job starts, and its finally block
released the slot unconditionally, wiping the claim the next job had just
made. Both the worker and the watchdog now release only what they still own
- rename Write-WinUtilJobProgress to Step-WinUtilJob. Write- in PowerShell
means adds to a stream, and this blocks while paused and throws
OperationCanceledException on stop. The trap was already live: the job layer
has to clear both flags before its own finish reporting or that reporting
re-raises the stop it is reporting
Also corrects the cross-runspace cost noted in the tests. Marshalling a
scriptblock is not "roughly twenty times" dearer; measured over 400 command
invocations it is 5354 ms against 3 ms rebuilt from text, because every command
the body invokes is resolved back through the originating runspace.
* refactor: drop the WinGet client module from this branch
The module is the one thing here that adds a runtime dependency: 53 MB from
PSGallery on first use, fetched at elevated privilege. It buys progress
movement inside a single package and nothing else. That is a different kind of
change from the rest of this branch, which only moves work between threads, and
it deserves to be judged on its own.
- remove Install-WinUtilWinGetClient and Invoke-WinUtilWinGetCommand
- collapse Install-WinUtilProgramWinget onto the command line path it already
had underneath, keeping the per-package result objects, so a failed package
still fails the job
- drop ProgressBase, ProgressSpan and Label from the winget path, which only
existed to slice the bar inside one package. Chocolatey keeps its own: it
reports per package from its own loop and never needed the module
- read upgradable packages from the winget command line output again
Kept on feat/winget-client-module, which branches from here.
* docs: follow the Write-WinUtilJobProgress rename in the architecture page
* fix: address the review findings on the job layer
Ten findings held up on inspection. The first two were breakage this branch
introduced.
- run a nested Start-WinUtilJob inline instead of refusing it. Install Features
reaches the job layer twice, once through its feature.json entry and again
from Invoke-WPFFeatureInstall, so the inner call was refused and features
never installed
- read the package manager preference rather than ChocoRadioButton.IsChecked in
Invoke-WPFInstallUpgrade, which runs on a worker where touching a control
throws
- pass parameters and return values through the Invoke-WPFUIThread fallback.
[action] carries neither, so Show-WinUtilMessage lost both its arguments and
its answer whenever the dispatch delegate was not yet built
- register a shell after BeginInvoke, not before: a NotStarted instance looks
finished to the pruning pass and could be dropped before shutdown saw it
- clear $sync.ActiveJobToken wherever the slot is released, through one
Clear-WinUtilActiveJob helper. Clearing only the name left a token that could
match a later run
- clear $global:WinUtilIsJobWorker when a worker finishes. Pool runspaces are
reused, so the flag outlived the job that set it
- set the pause and stop button state through the dispatcher
- take a locked snapshot of $sync.ActiveShells before enumerating it, and create
the collection under the lock
- stop the watchdog waiting on the interface thread. It issues the stop and
watches later ticks instead of sleeping for up to ten seconds
- throw rather than return on the ISO failure paths, which the job layer was
reporting as finished, and check exit codes in Invoke-WPFSystemRepair and
Invoke-WPFUltimatePerformance so a failed step fails the job
- give the pause and stop buttons AutomationProperties.Name; their content is a
private-use glyph
* fix: address the remaining review findings
Seven more held up. The first is the one that mattered most and this branch
introduced it.
- separate recycling a runspace pool from shutting down. Initialize-WinUtilRunspacePool
replaces a pool that is no longer open by calling Close-WinUtilRunspacePool,
which set $sync.ShuttingDown. Nothing resets it, so a single recycle made the
job layer refuse every later action for the rest of the session
- bound the ISO mount wait at 60 seconds. The loop had no exit but success, and
one job runs at a time, so a damaged or already-mounted image blocked every
other action and the shutdown wait
- check robocopy exit codes in both ISO and USB workflows through one
Invoke-WinUtilRobocopy. Codes of 8 and above mean files were not copied, which
produced media that reported complete and did not boot
- read oscdimg stderr as it arrives. Draining stdout first and stderr afterwards
deadlocks once the stderr pipe fills
- look for oscdimg on PATH, in both ADK roots and in the per-user WinGet package
root, using the same search before and after the install attempt
- set the child error preference to Stop for the profile setup, and fail on
captured error records. A non-terminating failure exited zero and was reported
as installed
- confirm each id parsed out of the winget upgrade table against winget before
upgrading it, and keep stderr out of the parse. The table is localised and
truncated, so a wrapped version or a translated header matched the same shape
* fix: address the minor and nitpick review findings
The review body carried 38 findings beyond the 20 inline ones, in collapsed
sections. These are the ones that held up.
Real defects:
- the theme hook assigned to $handled instead of $handled.Value, so a
WM_SETTINGCHANGE was never marked handled
- a declined UAC prompt left $elevated null and exited 0, which a headless
caller reads as a successful run
- Start-Transcript ran before the log directory existed, so the first run failed
before logging started
- Write-WinUtilLog appended even when the mutex wait timed out, which is the
case with the most contention and the one that interleaves lines
- Wait-WinUtilRemainingWork took [int] minutes, so any fractional timeout
truncated to zero and the bound meant "do not wait"
- the console progress throttle only applied when the text was unchanged, so a
job reporting per package wrote on every call
- an undecodable icon response stayed in the cache and was skipped on every
later run
- Start-WinUtilAssetRendering leaked its dedicated STA runspace; the cleanup
callback now disposes a runspace it was given
- Invoke-WPFFixesWinget could not repair a broken WinGet, because
Install-WinUtilWinget returns early when winget is detected. Added -Force
- winget's own reboot-required and reboot-initiated codes counted as failures
Smaller:
- set TLS 1.2 and a timeout before fetching the Chocolatey bootstrap
- let the headless queue drain survive one failing item, as the dispatcher path
already does
- bind the idle timer to the interface dispatcher explicitly
- route the export message through Show-WinUtilMessage like the import branch
- suppress New-Item output that was reaching the job's output stream
Tests that could not fail:
- the bounded-wait test passed a fractional timeout that truncated to zero, so
the wait never ran
- the slider tests cast possibly-absent attributes to [double], and compared two
empty strings for the regression they exist to catch
* fix: startup crash and icons that only appeared once the list was drawn
Both were mine, and both were introduced while addressing review findings.
The crash. Register-WinUtilRunspaceCleanup compiles its helper type once and
guards that with a type-exists check, so a session already holding the old
shape keeps it. Adding a Runspace property to that type therefore failed on
every later run with "The property 'Runspace' cannot be found". The type is
back to exactly what it was, and the asset rendering runspace lives until the
process exits: one STA runspace for the lifetime of the app is the cheaper
trade against a helper type that cannot be changed safely in a session.
The icons. Start-WinUtilIconFetch ran from Complete-WinUtilInstallAppRendering,
so nothing was fetched until every entry had been drawn and no icon appeared
for the first several seconds. Upstream assigned a remote address per Image and
let WPF fetch them all at once, which is what made them appear promptly.
- fetch after each render batch instead, gated so one fetch runs at a time and
whatever queues up meanwhile is taken when that fetch ends
- clear the gate when the runspace refuses the work, or no fetch would ever run
again for the rest of the session
- request each wave together rather than one icon after another
Measured on a cold cache in a VM: first icons at 1.35s and all of them by 4.0s,
against nothing before roughly 7s previously.
* fix: address the second review pass
All three are in code this branch added.
- accept DISM exit code 3010 as success. It is ERROR_SUCCESS_REBOOT_REQUIRED,
meaning the image was repaired and the change lands on restart, so the exit
code check added in the last pass turned a successful repair into a failed
job. Carried per step, since the same number from chkdsk or sfc does not mean
that, and logged as a warning so the restart is not silent
- say what is happening on the WinGet repair path. Install-WinUtilWinget -Force
runs while WinGet is installed, and printed "WinGet is not installed"
- append to PATH after installing Chocolatey rather than replacing it.
Overwriting with the machine and user values drops whatever this process
added earlier in the session
* fix: treat chkdsk's own exit codes as the outcomes they are
- chkdsk /scan reports 1 and 2 as ordinary results, so aborting the whole
repair on them skipped sfc and dism for no reason
- 3 stays a failure: the disk could not be checked, and the later steps are
not worth running on a disk in that state
- drive the decision off each step's SuccessCodes instead of a branch
hard-coded to DISM's 3010, so the same number means what that step means
- cover chkdsk 0, 1, 2 and 3, and 3010 from the wrong step
* fix: address the Codex review findings on the job layer
- send WPFPanel buttons that carry a function through the job layer: the
system corruption scan waited on chkdsk, sfc and dism on the interface
thread, with nothing to pause, stop or report it
- stop a timed out headless step before starting the next one, and abandon
the run if it will not stop, rather than changing the machine from two
runs at once
- keep the stop watchdog's slot claimed until the worker has actually gone
- skip the install summary reset when the Install tab has not been built,
which offline startup does by opening Tweaks first
- keep Win11ISO out of the tab warmup: building it runs the existing work
check, which reports or prompts while the user is on another tab
- pass --include-unknown when upgrading, since the scan that found the
packages used it
* fix: stop the tab warmup dying on a sync that is still growing
- Reset-WPFCheckBoxes enumerated $sync live while setting IsChecked, whose
handlers add to $sync, and while the warmup was building controls into it;
either one invalidated the enumerator and the warmup reported "Collection
was modified"
- snapshot both loops
- cover it with a checkbox that grows $sync from its own handler, which
reproduces the failure without the fix
* fix: shrink the pause and stop buttons and take them away when idle
- they were sized like the title bar icons, next to a 6px progress bar
- give them a size of their own and the smaller icon font, which font
scaling still applies to
- collapsed unless a job is running: they were only ever disabled, so a
finished or failed run left two dead buttons on screen
- the progress bar still stays to report how the run ended
* fix: colour the progress bar by how the run ended
- only the taskbar item carried the state, so a run that finished with
errors left a full bar in the normal colour, reading as a clean finish
- the fill now follows the bar's Foreground, which the job layer points at
an error or warning colour and back again
- by resource reference, so switching theme repaints it
- add error and warning colours to both themes
* fix: stop rendering the app navigation twice, which left Install dead
- upstream moved the app navigation render into Initialize-WPFUI, and this
branch still rendered it beforehand, so it was built twice
- the second pass clears the target grid, and the "already wired" guard goes
by name, so the replacement buttons counted as wired and never got a click
handler: Install and Uninstall did nothing, with no error anywhere
- leave that render to Initialize-WPFUI
* fix: uninstall apps that belong to the signed in user
- WinGet answers APPINSTALLER_CLI_ERROR_ADMIN_CONTEXT_ACTION_PROHIBITED for
anything installed in user scope while it is running elevated, and WinUtil
is always elevated, so those uninstalls did nothing
- a process cannot drop its own elevation, so hand that one command to a
scheduled task running as the interactive user at limited run level
- retry only on that code, so everything else is untouched
* style: keep the ISO variable names the file already used
- new scriptblock parameters were named in PascalCase, which put 20 lines
into the diff that are otherwise identical to main
- nothing about the behaviour changes
* refactor: take the icon cache out of the job layer change
It is its own feature, not something consolidating background work needs.
Entries go back to assigning the favicon address to the image, as main does.
The work is kept on feat/install-icon-cache and follows once this lands.
* refactor: take pause and stop out of the job layer change
They are a new feature of their own, not part of consolidating background
work, and main has nothing like them today.
- drop the two buttons, their routing and the checkpoints that served them
- keep Stop-WinUtilActiveWork: closing the pool and the headless step
timeout both need to end work, and neither is the user pressing a button
The work is kept on feat/job-pause-stop and follows once this lands.
* refactor: drop changes the job layer does not need
- the icon glyph strings are a rendering fix of their own: main renders a
char, and whether that is right has nothing to do with background work.
Reverted here, kept on fix/ui-glyph-strings
- trim the temp cleanup tweak to the part this change forces: errors have to
be suppressed because the job layer counts a logged error as a failed
step, but counting what was removed is unrelated polish
* refactor: cut comments and wrappers that were not earning their place
- the Recycle switch explained itself over four lines; two say what a reader
needs to know
- drop a .PARAMETER that only restated the parameter name
- Unregister-WinUtilActiveShell had one caller and cost twenty lines, so it
is inlined
- the running check was the same try/catch three times over, now one helper
* refactor: comments describe the code, not how it got here
- remove five comments left pointing at code the icon and pause splits took
away, two of them sitting above unrelated lines
- cut the ones that recounted a bug rather than describing behaviour: the
double rendered navigation, the dropped [action] parameters, the shell
registered too early, the Add-Type shape
- shorten the rest to what a reader needs
* refactor: inline the winget error message at its only call site
- Get-WinUtilWinGetErrorMessage was 26 lines for a one line format string
- Its zero guard was dead: exit code 0 is handled by an earlier branch
- Drop the file and the two test dot-sources of it
* refactor: drop the user scope uninstall fix, it has its own branch
- Invoke-WinUtilUnelevated and the elevation retry are self contained
- They ship on fix/winget-user-scope-uninstall, which does not need the job layer
- Removes a file and 3 tests from a PR that is already large
* docs: tighten function help and comments
- Cut narrative framing from the job layer, queue and shutdown doc blocks
- Kept the technical reasons, dropped the restatements around them
* docs: drop comments that restate the code
- Consent check, powercfg exit codes, shortcut guard, rethrow, single reason
- Compact the UI thread helper's help
* fix: address async job layer review findings
* fix: harden job startup and dependency discovery
* fix: close remaining async review gaps
* fix: finalize shutdown and ISO recovery paths
* fix: guarantee job cleanup and error attribution
* fix: preserve job outcomes during cancellation
* fix: close async rendering and logging races
* fix: bound shutdown and surface UI startup failures
* fix: skip blocked user-scope install updates
* fix: address final PR review findings
* fix: warn on blocked user-scope package actions
* fix: propagate file-backed headless exit codes
* Address final async job review findings
* Resolve latest automated review findings
* Preserve clipboard history in activity tweak
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* feat: add title screen generation tooling
Add local automation for capturing WinUtil in Light and Dark themes
and generating the composite title-screen image.
* ci: automate title screen updates
Add a manual Windows workflow that compiles WinUtil, generates the
Light and Dark composite, and opens an image-only pull request.
* docs: update AGENTS.md and SPEC.md with title-screen generation details
* fix: address review comments
Tested image is correct, SHA-256 hash is identical to the previously verified output.
* fix: deselect bitmap before reading capture pixels
* chore(tweaks): clarify Activity History tweak description
* fix(tweaks): preserve clipboard history
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Add tweak to block Logitech Download Assistant auto-install
Mirrors the WPFTweaksRazerBlock folder-deny approach: clear
C:\Program Files\LogiDownloadAssistant, recreate it empty, and deny
Everyone write access so the Windows Update software-component package
cannot re-deliver the payload. UndoScript removes the deny ACE.
Unlike the Razer tweak, no global SearchOrderConfig/DisableCoInstallers
registry changes: those alter driver search system-wide and do not stop
software-component packages.
Fixes#5029
* Harden Logi block tweak per review: SID, 64-bit path, exit codes
- Use the locale-independent *S-1-1-0 SID instead of the English
"Everyone" name, which fails to resolve on non-English Windows.
- Resolve the 64-bit Program Files directory via ProgramW6432 with a
ProgramFiles fallback, so a 32-bit host cannot target the x86 folder.
- Throw when icacls exits non-zero so Invoke-WinUtilScript logs the
failure instead of reporting the tweak as completed.
- Skip the undo icacls call when the folder no longer exists.
* fix(iso): inject drivers per package
Add each root package folder separately so one bad driver cannot fail the rest. The batch form is roughly four times faster. That cost is accepted for one deterministic code path
* Preserve retained nested driver packages
* Discard partial driver injection attempts
* Remove excluded nested driver INFs
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* docs: fix typo in contributing image asset and markdown references
* docs: fix typos and grammatical phrasing in documentation
* fix(config): correct typographical errors in tweak and app descriptions
* fix(scripts): resolve typos and grammatical errors in PowerShell sources
* fix: address review feedback on Outlook description, WinUtil capitalization, and grammar
* fix(win11-creator): filter unserviceable and stale drivers before injection
Add-Driver aborts the whole batch when one exported package is bad,
which broke ISO creation for anyone with an Extension-class or stale
duplicate driver in their store (#4971, #4982). Exclude both before
the single Add-Driver call instead of guessing per-vendor.
* fix(win11-creator): address driver filtering review feedback
Accept date-only DriverVer entries instead of treating them as
unknown. Use the full folder path as the dedup fallback key so two
unrelated packages can't collide on a shared leaf name. Discard the
logger's own output inside the selector so an emitting -Log callback
can't inflate the survivor count. Skip driver injection instead of
failing the whole ISO build when nothing is left to inject.
Also extracts the repeated DISM mock setup in the driver tests into
one shared harness, and asserts that excluded packages are actually
deleted from the export root before Add-Driver runs, not just logged.
* fix: address remaining code review comments
* feat(github): Prettify bug report template
* Let the people know that if they include anything private and share it, that makes them stupid, because AI told me to do that and that's NOT THAT OBVIOUS(sarcasm sign)
* Fix backward compatibility for old-style JSON config imports
* Refactor sidebar UI generation and add tests for Get-WinUtilVariables
* Fix appnavigation config test following UI generation refactor
* Restore global sync state in variables tests
* fix(impex): migrate supported legacy selections
Keep modern imports strict while allowing legacy backups to skip retired entries with clear logging and user feedback. Add fixtures covering partial and all-retired imports.
* test: strengthen UI and global state coverage
Exercise app category rendering through Initialize-WPFUI and restore global sync without leaking test state.
* fix(impex): ignore legacy metadata fields
Limit legacy selection migration to supported WPF key families so unrelated string metadata does not produce false retired-setting warnings.
* docs: clarify legacy config imports
Distinguish strict modern flat imports from partial legacy object migration, including single-setting export shape and historical groups.
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Add Get-WinUtilEntryToolTip helper for preset-key tooltips
* Show preset JSON key in app and tweak tooltips
* Match apps search against preset key for consistency with tweaks
* Limit preset-key tooltips to preset-representable controls
Comboboxes and package-manager radio buttons cannot appear in a preset
file. Update-WinUtilSelections routes a flat list of keys by the
WPFInstall/WPFTweaks/WPFToggle/WPFFeature/WPFAppx prefixes, so a preset
can carry neither a combobox selected value nor a radio group choice;
WingetRadioButton and ChocoRadioButton do not even carry a WPF prefix.
Advertising those control names as preset keys invited users to add keys
that fall through the switch and abort the whole import.
Revert the combobox label and radio button tooltips to the plain
description, and add tests that fail if the key is reattached to a
control the preset importer cannot accept.
* fix: address preset key review feedback
* docs: clarify preset key search scope
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* fix(apps): WARP prettify
Updated Cloudflare WARP entry with new key and modified description and link.
* Fine, Chris, let's leave property name as full
* Rename 'cloudflare-warp' to 'CloudflareWARP'
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* feat(github): revival of triage tools
* fix(github): workflow doc fix
* fix(github): PR detection
* fix(gh): wontfix preserve bug label
Removed state_reason from issue update when adding wontfix label.
* fix(gh): doc cleaning
* one more thing
* fix(gh): prevent Gabi moment
That's the only thing I will agree with this piece of hardware
* Fix syntax error in triage-tools.yaml
* fix(github): restrict triage commands to issues
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Add EmulationStation and Tailscale entries to applications.json
* Update config/applications.json
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update config/applications.json
I'm so sorry I'm late I've had to take a break from this for a bit of health related stuff.
Co-authored-by: Ivan Lepekha <57459428+FluffyPunk@users.noreply.github.com>
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Ivan Lepekha <57459428+FluffyPunk@users.noreply.github.com>
* feat(apps): Added Battle.net
Just Blizzard. Well, we can hate them, but their launcher is unique
* You know, being smart is a hard work...
* titusTypo
* fix: link apps to their own site instead of a repo or store page
- the icon comes from the link's domain, so every GitHub hosted app showed
the same octocat and the two store apps showed the Microsoft Store tile
- point 16 apps at the project's own site, and LibreWolf at librewolf.net
rather than its old gitlab.io address
- left on GitHub where the site turned out to redirect back to the repo
(fnm, MSEdgeRedirect, Deskflow) or has no icon to serve (gsudo,
simplewall, ungoogled-chromium, DISMTools)
* fix: point Teams at teams.live.com so it shows the Teams logo
- the marketing page on microsoft.com serves the generic Microsoft favicon,
which Edge already uses
* fix: keep GlazeWM and Lua on the pages that match what is installed
- glazewm.com is not the project's own site: the repo declares no homepage,
glzr.io never references it, and it runs on unrelated hosting
- lua.org is the language, while the package is Lua for Windows
* fix: keep Teams on the Microsoft product page
- the package is Microsoft.Teams, the work product, while teams.live.com is
the consumer edition
FontScalingSlider had no AutomationProperties.Name, so screen readers
announce it as an unnamed slider with only a raw numeric value.
Completes the accessible-name coverage of the font scaling popup.
ThemeButton, FontScalingButton, SearchBar, and SearchBarClearButton had
no AutomationProperties.Name, so screen readers (Narrator, NVDA)
announce them as raw glyph text ("N/A", Unicode E8D3), an unnamed edit
field, and a button called "X". Completes the top-bar naming pass
started for SettingsButton and the window controls.
* Containerize the docs site's npm tooling
Run Astro/Starlight dev, build, and preview commands through Docker
(docs/Dockerfile, docker-compose.yml, service winutil-astro) instead
of bare npm on the host, and document the required commands and
rationale in docs/README.md.
* Document Docker-only npm policy for agents
Add a Dependency Installs, Builds, And Dev Servers section to
AGENTS.md requiring docs/ tooling to run through Docker rather than
directly on the host, point SPEC.md's Docs Site section at the new
Dockerfile/docker-compose.yml, and renumber the remaining AGENTS.md
sections to stay sequential.
* Harden docs Docker dev environment
Tightened docs-container safety and clarified contributor workflow. The docs Docker image now switches to the non-root `node` user after setting ownership, and compose now binds Astro to `127.0.0.1` instead of all interfaces. Updated AGENTS and docs README instructions to explain the security boundary of the bind mount and to require rebuilding plus `docker compose down -v` after dependency changes so `node_modules` is reseeded correctly.
* Clarify docs secret handling in AGENTS
Updates AGENTS.md to tighten docs security guidance: secrets must not be stored anywhere under `docs/`, because `docs/.dockerignore` only affects image build context and does not protect files from the Docker Compose bind mount used for docs dev/build commands.
* Fix preview command to expose port in Docker
The previous preview command didn't expose the port outside the container. Adding --service-ports and binding to 0.0.0.0 makes the preview server accessible from the host.
* Update dns.json
* Fix Mullvad DNS review issues
* Add Mullvad secondary resolvers
* Register DoH before changing adapter DNS
* Report DNS failures to tweak workflow
* Handle non-terminating DNS assignment failures
* Preserve DNS fallback and document Mullvad options
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Fix UI automation peer wrapping and category focusability
* Add accessibility name to SettingsButton
* Avoid nesting ScrollViewer in generated panels with outer viewers
Inspect targetGrid and its parent hierarchy in Invoke-WPFUIElements to avoid adding an inner ScrollViewer when an outer ScrollViewer already exists.
* Turn the Install category filters into toggle chips
- Replace the filter buttons with toggles that show which ones are active
- Add ctrl click to select more than one category
- Keep the search box and the category filter independent of each other
- Expand matching categories while a filter is active
* Fix the filter interactions the category chips missed
- Pass the selected categories to the lazy rendering batches, the old call
used a parameter that no longer exists and threw while typing
- Keep the category filter when switching tabs, the chips stayed checked
while the filter itself was dropped
- Put a category back to collapsed once the filter that expanded it is gone
* Document the Install category filters
- Add a guide section for the chips, ctrl click and clearing the filter
- Note that search and the category chips apply together
* Correct the category filter guide wording
- Clearing by clicking the chip only applies when it is the only one selected
- Only categories with matches expand, and only auto expanded ones re-collapse
* Point OpenSSH key setup at the file sshd actually reads
The Remote Access feature created %USERPROFILE%\.ssh\authorized_keys and
told the user to put their public keys there. sshd does not read that
file for a member of the administrators group; the "Match Group
administrators" block in sshd_config sends those logons to
C:\ProgramData\ssh\administrators_authorized_keys instead. WinUtil always
relaunches itself elevated, so the account it was setting up is always an
administrator, and key auth for it never worked.
The function tried to work around that by commenting the block out, but
those regexes anchor on $, and .NET puts $ before the \n of a CRLF pair.
The sshd_config Windows ships is CRLF throughout, so the replace was a
silent no-op on a stock install. On an sshd_config with LF endings it did
apply, and that is worse than not working: sshd gives an administrator
logon a full token with no UAC prompt, which is why Windows keeps those
keys in ProgramData behind an ACL that requires elevation to write.
Moving the lookup into the profile lets anything running as the user at
medium integrity append a key and get an elevated shell unprompted.
Use administrators_authorized_keys and give it the ACL sshd requires
(inheritance off, Administrators and SYSTEM only, by SID so localized
installs work). Where the sshd_config edit did land, undo it and copy any
keys out of the profile file first so key auth is not cut off mid-session.
Keys are only copied when the block needs restoring, so a default config
never grants access sshd was not already granting.
Also stop creating the profile .ssh directory: under elevation it was the
elevating administrator's profile, not necessarily the caller's.
* Document where to put SSH keys for the OpenSSH server feature
* Make UI helpers no-op when no window exists
The -Preset and -Config paths run Invoke-WinUtilAutoRun before the XAML
form is created and before PresentationCore is loaded, so every call into
Invoke-WPFUIThread failed with InvokeMethodOnNull and every call into
Set-WinUtilTweaksProgressIndicator failed to resolve [Windows.Visibility].
The errors were non-terminating, so tweaks still applied, but each run
filled the log with noise.
Loading presentationframework earlier does not help: Visibility lives in
PresentationCore, which only loads once a WPF object is instantiated, and
the XAML-named progress controls do not exist in these paths either.
Guarding the two helpers covers Invoke-WPFtweaksbutton, Invoke-WPFundoall
and Invoke-WPFFeatureInstall, which the existing per-call-site $hasUI
convention never reached.
* Suppress stray console output from automation runs
Invoke-WPFRunspace returns an IAsyncResult that no caller uses, and
Set-WinUtilRegistry was the only New-PSDrive call site that did not
suppress its output. A GUI click handler discards both, but the -Preset
and -Config paths call the workflows directly, so an async handle dump
and a PSDrive table landed in the user's log.
The handle itself is kept because pester/runspace.Tests.ps1 asserts that
Invoke-WPFRunspace returns a single IAsyncResult, so the suppression goes
at the four call sites reachable from Invoke-WinUtilAutoRun.
* Add project learning for window-free UI helpers
Tabs other than Install build their checkboxes lazily on first visit.
Import populates $sync.selected* and calls Reset-WPFCheckBoxes, but
that only touches checkboxes that already exist in $sync, so any tab
not yet visited gets its controls built later with default (unchecked)
state and never reflects the import. Re-apply Reset-WPFCheckBoxes right
after a tab's controls are built so it picks up existing selections.
mpv has no official Windows installer; winget id shinchiro.mpv is the
de facto standard Windows build. Choco mpv/mpv.install are flagged
"Possibly broken" upstream, so winget is the sole install source.
* Add SEO metadata to docs home
Add a robots.txt sitemap directive and JSON-LD SoftwareApplication metadata to the docs homepage to improve search engine discovery and rich results.
* Add social preview metadata
Add Open Graph and Twitter image metadata for the docs site and include a new shared social preview image. Also set the homepage title metadata to match the documentation branding.
* docs: correct Win11 Creator behavior after the ISO workflow refactor
The creator stopped stripping unused editions, loading offline registry
hives, and running component store cleanup in #4862. It now copies the
ISO contents and applies the selected edition through sources\ei.cfg and
autounattend.xml, leaving install.wim alone unless drivers are injected.
Update the guide and the architecture reference to match, and note that
the output ISO is close to the size of the source.
* docs: align disk space, driver injection, and stuck-run guidance
The disk space block still carried the pre-refactor 10-15 GB workspace,
2.5-3.5 GB output, and ~25 GB total, which contradicted the copy-based
numbers in the data flow. Restate them against the source ISO size.
Driver injection never touches boot.wim. It adds every exported driver
to the selected install.wim index and stages only the storage packages
in $WinpeDriver$ for WinPE, so correct both the guide and the reference.
The stuck-run troubleshooting entry pointed at a WIM dismount that only
happens when driver injection is enabled.
* docs: narrow this PR back to the edition and output size claims
The earlier commits rewrote the surrounding Win11 Creator sections,
which went well beyond what #4918 was about and presented the rest of
the section as reviewed when it had not been.
Restore the untouched text and keep only the claims that promised a
size reduction or edition removal: the strip-editions and component
store bullets, the two data flow lines, and the modified ISO size.
* Replace FOSS dot with a corner badge on app entries
- Add New-WinUtilFossBadge, the open source keyhole on a green backdrop
- Mark FOSS apps with a corner triangle instead of a dot after the name
- Give the FOSS legend a circle badge and move it below the buttons
- Sort Note entries last, they shared a rank with checkboxes before
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Update functions/private/Initialize-InstallAppEntry.ps1
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Centralize agent instructions in SPEC
Move the full coding-agent contract and repository guidance from `AGENTS.md` into `SPEC.md`, and reduce `AGENTS.md` to a simple pointer to the canonical instructions. Add lightweight `CLAUDE.md`, `GEMINI.md`, and `.github/copilot-instructions.md` files so different assistants consistently bootstrap through the same repo-specific guidance.
* Clarify auto-generated docs path scope in SPEC
Narrowed rule #3 to specify exact auto-generated subdirectories (tweaks/ and features/) rather than the entire code-reference/ directory, and clarified that other hand-written pages (e.g. architecture.mdx) may be edited directly.
* Remove archived docs from gitignore
Drop the old `docs-old` Hugo ignore rules from `.gitignore`, reflecting that the archived docs build artifacts no longer need special handling there.
* Add local env files to docs .gitignore
Add .env.local and .env.*.local patterns to prevent local environment files from being committed.
* Clarify test and git hygiene guidance
Update `SPEC.md` to run Pester in CI mode and tighten repository hygiene instructions around ignored files. The git guidance now points contributors to the actual `.gitignore` files and clarifies that `docs/public/` contains tracked static assets rather than generated output.
* Split agent workflow from project spec
Move repository working instructions into `AGENTS.md` and refocus `SPEC.md` on the stable WinUtil project contract. This separates agent-specific guidance from architecture, build, runtime, docs, testing, and release details so both documents have clearer ownership.
* docs: clarify Pester, ScriptAnalyzer, and source-of-truth rules
Expand AGENTS.md with context on why -SkipPublisherCheck is needed for Pester installation, why winutil.ps1 should be deleted before running ScriptAnalyzer, and clarify that the source-of-truth rule applies only to compiled-script behavior — repository metadata files are edited directly.
* Clarify Pester install command and -SkipPublisherCheck reason
Expands the explanation for why -SkipPublisherCheck is needed (catalog-signed vs Authenticode-signed), clarifies it does not skip download integrity, and adds -Repository PSGallery to pin the trusted source explicitly.
* feat: restore document category
Moves existing document-focused apps into the Document category and adds its filter chip.
* feat: restore document applications
Restores reviewed document-focused apps removed in PR #4451.
* chore: update apps list as per code review comments
This also updates the link for PDF24 Creator
* test: verify document category filter wiring
Covers the Document filter handler and config category presence.
* fix: categorize Calibre as multimedia
Keeps the e-book reader in Multimedia Tools.
* fix: repair popup install binding, dialog titles, presets switch, radio groups, JSON, tests
- Invoke-WPFInstall: add param block so the right-click app popup binds
-PackagesToInstall. It previously dropped the argument into $args and
installed the whole selected list instead of the clicked app (or warned
that nothing was selected).
- Replace undefined $AppTitle with "WinUtil" in Install/UnInstall warning
boxes, matching the XAML window title and sibling dialogs.
- tweaks.json: remove stray nested "link" inside the WPFToggleScrollbars
registry entry (dead property; registry entries expose only the six
consumed fields).
- Invoke-WPFPresets: fix dead switch cases to the wildcard-pattern
convention so selectedFeatures/selectedToggles clear correctly.
- Invoke-WPFUIElements: store the group StackPanel in radioButtonGroups so
grouped radio buttons share one container (else branch was unreachable).
- sanity.Tests.ps1: pass the Windows PowerShell parser script via
-EncodedCommand; -Command string marshaling corrupted backticks/quotes and
produced false parse failures.
- install-workflow.Tests.ps1: remove the AppTitle workaround and update
title assertions to "WinUtil"; drop orphaned cleanup lines.
- Add CHANGES.md with technical and plain-language explanations.
Verified: each bug reproduced against HEAD, fixes demonstrated to change
behavior, full Pester suite 471/471.
* Delete
* test: cover the explicit popup install parameter path
Add a regression test invoking Invoke-WPFInstall -PackagesToInstall with a
package different from the default sync.selectedApps selection and assert
the runspace receives the explicit object, mirroring the Initialize-WPFUI
popup call shape. Existing default-path coverage is unchanged.
Add the `YouTubeEmbed` component import to `docs/src/content/docs/guides/tweaks.mdx` so the guide can use embedded YouTube content without missing-component build issues.
Update image links in `.github/CONTRIBUTING.md` and `.github/READMEITALIAN.md` from `../docs/...` to `/docs/...` so screenshots resolve correctly when viewed from the `.github` directory context on GitHub.
The homepage uses Starlight's splash template, which has no sidebar and
therefore never gets Starlight's own mobile menu toggle - on narrow
viewports there was no way to reach any nav link at all. Add a small
toggle + panel in the header (only rendered on pages without a sidebar)
exposing the same links as the desktop nav, and group it with the
search icon so mobile actions sit together instead of spread across
the header.
Also add the Store and Forums links to the real sidebar config so
they're reachable on mobile on every other page too (previously only
in the desktop-only top nav), and pull both URLs from a shared
site-links.ts so the sidebar config and header can't drift apart.
* Update Applications tab screenshots
Replace outdated install/uninstall/show-installed screenshots and add
new ones for upgrade-all, clear-selection, selected-apps counter, and
collapse/expand categories.
* Update Applications guide with new screenshots and sections
Point each tab at its refreshed screenshot, reorder tabs to match the
sidebar button order in the app, and document the Upgrade All,
Selected Apps counter, and Collapse/Expand Categories controls.
* Add missing Updates tab screenshot
The image was referenced by the Updates guide but was never checked
into the repo.
* Reorder screenshots to follow their intro paragraph
Move the tab screenshot below the introductory text on the Tweaks and
Updates guide pages, matching the paragraph-then-screenshot layout
used elsewhere in the docs.
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Fix the same arrow-icon alignment issue on the "Read the Docs" button
Same root cause as the hero/final-CTA buttons: the label was plain
markdown text, which MDX wrapped in a <p>, and the icon was missing
the size/nudge applied elsewhere. Match it to the other two buttons.
* Rename known-issues page slug to knownissues
Update the sidebar config, nav dropdown, and every internal link that
pointed at /known-issues/ to match.
* Fix image paths in root-level markdown to match the new docs site
The Hugo docs site (docs/assets/images/...) has been replaced by the
Astro site (docs/src/assets/...); update CONTRIBUTING.md,
READMEITALIAN.md, and README.md to point at the new asset locations.
* Remove unused houston.webp asset
Leftover Starlight default-theme asset with no references anywhere
in the docs site.
* Fix docs site reference in generator docs
Updates `tools/devdocs-generator.md` to describe link generation correctly: links now point to the Astro/Starlight documentation site instead of the old Hugo site.
* Point docs homepage CTAs to guides hub
Updates the docs landing page CTA links to use `/guides/` instead of `/guides/getting-started/` in the hero action and both “Get Started”/“Read the Docs” buttons, routing users to the guides index.
* Add reusable YouTube embeds to docs guides
Introduces a new `YouTubeEmbed.astro` component for responsive 16:9 video embeds using the privacy-enhanced `youtube-nocookie.com` domain. The User Guide index and Tweaks guide now import and use this component instead of plain YouTube links, and the component includes styling that overrides Starlight’s iframe reset so embedded videos render at the correct size.
* Fix YouTube embed iframe height via not-content
Add the `not-content` class to the embed wrapper so Starlight's markdown reset no longer overrides `iframe { height: auto }`. Drop the `@layer starlight.core` wrapper and `!important` overrides that were compensating for the same issue.
* Clarify docs comments across Astro components
Adds and refines inline comments in the docs site config, custom Starlight components, and theme styles to better explain layout structure, navigation dropdown behavior, hero composition, and theme initialization. Also normalizes a few multi-line comments into single-line form for readability without changing functionality.
* Set secondary docs button background color
Update `.wu-btn-secondary` in the docs theme to use `var(--sl-color-gray-6)` instead of a transparent background, improving button visibility and contrast while keeping existing border and hover behavior.
* Move User Guides into docs dropdown
Updates the docs header navigation so the “User Guides” link is grouped under the existing “Documentation” dropdown instead of appearing as a separate top-level nav item. This keeps related documentation links together and simplifies the top navigation.
* Fix hero margin and center trust section
Remove the automatic 1.5rem top margin Starlight adds between the hero and the content column. Also flex-center the trust section so its content is properly aligned.
* Disable edit links in generated dev docs
Update `tools/devdocs-generator.ps1` to include `editUrl: false` in the frontmatter for generated tweak and feature docs pages. This prevents Starlight from showing edit links on these auto-generated pages.
* Move docs update PRs to pre-release flow
The docs Pages workflow is simplified to only build and deploy the docs site: it now triggers only on docs changes, drops extra permissions/default shell settings, and removes the dev-docs generation + auto-PR steps. The pre-release workflow now owns that automation by expanding its PR step to include generated code-reference docs alongside JSON link updates, with updated commit/title/body text and a documentation label.
* Shorten generated docs source note
Simplify the autogenerated DevDocs notice so generated pages only warn against direct edits while still linking back to the source file.
* Improve docs header dropdown behavior
Reworked the header nav dropdown triggers to use native `<details>/<summary>` instead of buttons, then updated menu visibility logic to use `details[open]` for no-JS support on touch and keyboard while preserving hover behavior. Also renamed the “Developer Docs” link to “Code Reference” and tightened related CSS comments.
* Refresh contribution and docs workflow docs
Updated contributor-facing docs to use consistent Markdown admonition blocks, cleaned Mermaid fence formatting, and fixed minor wording/capitalization in contribution steps. Clarified `devdocs-generator` behavior so workflow ownership is explicit: generation now documented as part of `pre-release.yaml` (via docs-update PR), while `docs.yaml` is documented as build/deploy only.
* Fix contributing guide grammar
Correct the "it's" to "its" typo in both contributing guides so the pull request guidance is consistent across the GitHub and docs versions.
* feat: Add DoH templates for DNS providers in configuration
* feat: Implement DoH support for DNS configuration and management
* feat(pester): enhance DNS tests to include DoH server address handling and template application
* fix: address codex feedback
* fix: update existing DoH server entries
* fix: enable DoH auto-upgrade
* fix: handle DNS setup failures
* fix: remove DoH state on DHCP reset
* refactor: simplify Win11 Creator ISO workflow
Keep no-driver ISO generation on the fast copy-only path.
Inject exported drivers with one selected-index WIM mount, one Add-Driver pass, and one commit.
Limit WinPE staging to boot-storage drivers and improve workflow validation coverage.
* refactor: stage Win11 setup script fallback
Copy the prepared setup script payloads into sources/$//Setup/Scripts so setup media does not depend solely on answer-file extension extraction.
Keep the existing autounattend execution path unchanged and cover the fallback files in the Win11 Creator tests.
* refactor: address codex feedback
* refactor: run ISO verification in runspace
Rename the ISO logger to Write-WinUtilISOLog so the shared runspace pool imports it automatically. Run Mount & Verify off the WPF thread with dispatcher-safe UI updates, and add Pester coverage for the runspace and logger contract.
* refactor: address ISO review feedback
Keep the selected ISO stable during background verification. Apply ContentDeliveryManager settings to both the first account and the default profile. Block FAT32 USB creation when install.esd exceeds the supported file size.
* refactor: address ISO setup edge cases
Set BypassNRO before OOBE so local account setup is available during Windows Setup.
Detect registered DISM mounts during driver-injection cleanup so partial mount failures are discarded.
* refactor: address ISO review edge cases
Use the actual FAT32 file limit for install.esd USB checks.
Disable ISO modification while mount verification is running.
Apply unsupported-hardware notice suppression to the first user profile.
* refactor: stage ISO setup safeguards earlier
Set device encryption and reserved-storage registry guards before OOBE.
Enable the OEM configuration-set fallback when setup scripts are staged there.
* Update functions/private/Invoke-WinUtilISOUSB.ps1
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---------
Co-authored-by: Chris Titus <contact@christitus.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* refactor: implement FilterChipStyle for Install tab category filters
- Created a dedicated FilterChipStyle style block with custom padding, cursor, and height definitions
- Applied FilterChipStyle to all category filter buttons
- Added a new 'Filters' TextBlock section title aligned with the sidebar actions
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Chris Titus <contact@christitus.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Add Quick Category Search Chips to Install tab
Add category shortcut chips on the Install tab that insert the category
name into the existing search box. Append each app's category as a
description tag so the existing description search filters by category.
Reuses the standard button style and existing search; no search, install,
or preset logic is changed.
* Fix install category chip filtering
* Fix category filter refresh behavior
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* fix(search): make search bar stretch instead of overflowing at narrow window sizes
* fix(ui): sync runtime MinWidth override with XAML value
Add_Loaded was hardcoding $sync.Form.MinWidth back to 1000 after
load, overriding the 1150 set in inputXML.xaml and letting the
window shrink below the space the search bar/toolbar layout needs.
* fix(ui): address responsive search review feedback
* fix(ui): enforce usable toolbar width
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Add maximize button logic and update assets
* Add maximize button with theming
* delelte logo
* Center and restyle the window control buttons
* Fix window state test setup
---------
Co-authored-by: aran628 <aran2014+@gmail.com>
Co-authored-by: Chris Titus <contact@christitus.com>
* feat(tweaks): add window-level progress indicator for Run Tweaks and Undo
* Hide completed tweaks progress on next action
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* fix: resolve silent failures in AppX removal and PS7 DISM bugs
- Fixed a bug where Remove-AppxPackage failed silently in PowerShell 7 due to pipeline binding issues. We now explicitly loop through Get-AppxPackage results and pass PackageFullName directly.
- Added wildcard matching to Get-AppxPackage and Get-AppxProvisionedPackage to reliably locate packages regardless of short name vs family name variations.
- Offloaded Get-AppxProvisionedPackage and Remove-AppxProvisionedPackage execution to Windows PowerShell 5.1 (powershell.exe) to bypass PowerShell 7 DISM COM exceptions ("Class not registered") and performance hangs.
- Deduplicated AppX removal logic by calling Remove-WinUtilAPPX directly from Invoke-WPFAppxRemoval instead of copying the implementation.
* refactor(Remove-WinUtilAPPX): use script block to improve readability
* feat: enhance AppX removal process and add provisioned package removal function
* fix(tests): update AppX removal tests
This also adds tests for the new Remove-WinUtilProvisionedAPPX functionality
* Move AppX removal under Tweaks
* Address AppX removal review feedback
* Complete AppX removal error handling
* Prevent AppX cleanup confirmation prompts
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* feat(legacy-panels): add Firewall, Security, Programs, and Mouse to Legacy Windows Panels
- Added `firewall.cpl`, `wscui.cpl`, `appwiz.cpl`, and `main.cpl` to `config/feature.json`
* chore(legacy-panels): alphabetize panel entries
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Create app suggestion discussion template
Add a discussion template for app suggestions with rules and input fields.
* Add application suggestion link to issue template
Added a link for suggesting applications to the issue template.
* Update app suggestion discussion template
* Add checkbox for WinGet application presence check
* Changed name of file, didn't change name of link XD
* Add WinUtil version input to bug report template
Added input field for WinUtil version in bug report template.
* whoops :^)
* Someone forgot that label is single value parameter
* GH Wiki is a liar
* GH Docs are looking awful
* Talk about "PowerShell 7 from the Microsoft Store" inside of KnownIssues.md
* Update Invoke-WinUtilInstallPSProfile.ps1
* Update KnownIssues.md
* Update KnownIssues.md
* Update KnownIssues.md
* feat: Enhance Win11 Creator with edition ID handling and update autounattend.xml generation
* Strengthen Pester coverage for config and function files
* Create app suggestion discussion template
Add a discussion template for app suggestions with rules and input fields.
* Add application suggestion link to issue template
Added a link for suggesting applications to the issue template.
* Update app suggestion discussion template
* Add checkbox for WinGet application presence check
* Changed name of file, didn't change name of link XD
* Replace FOSS highlight toggle with inline label
Remove the separate "Highlight FOSS" toggle and its theming logic, and instead append an inline "- FOSS" label to FOSS app entries. Changes: remove WPFToggleFOSSHighlight from app navigation and related event handlers, delete FOSSColor resource updates in theme code and button handler, simplify checkbox setup in Invoke-WPFUIElements by removing the special-case toggle logic, and update Initialize-InstallAppEntry to build a horizontal panel containing the app name plus a small green "- FOSS" TextBlock for FOSS items. This consolidates FOSS indication into the item UI and cleans up toggle/theme handling.
* Add inline FOSS label to app entries
Replace the separate StackPanel/TextBlock used for the FOSS indicator with an inline System.Windows.Documents.Run appended to the app name. The run is styled (green RGB(76,175,80) and FontSize=10) and the checkbox content assignment was moved outside the conditional so the appName (with optional FOSS run) is always used. Cleaned up related comments to reflect the FOSS label change.
* Add FOSS note type with green bullet
Added FOSS notes in the UI and FOSS labels with a green bullet instead of the text '#FOSS'
* Use larger circle glyph; remove italic text
Replaced the FOSS and list bullet glyphs with a larger circle for better visual consistency and removed the italic styling
* Update FOSS/bullet glyphs, colors and sizes
Updated FOSS/list bullet styling by switching glyphs from U+2B24 to U+25CF, increasing size (10→11.5), and adjusting bullet/text colors for better visibility and consistency across.
* Fix slop remains
Chris likes to vibe code. AI likes to use different types of dashes (em-dashes, en-dashes), instead of regular dashes (-).
On PowerShell 7 this appears to work. The parser doesn't care. But, what about PowerShell 5? It begins throwing errors about the ampersand. Loading it in the ISE reveals how it stops parsing the syntax correctly when it encounters em-dashes. Rather than displaying them as such, the ISE displays them as —.
Chris, if you want to vibe code, I don't mind. But at least use regular dashes.
Anyway, I won't fix the AI code. I just want to make it work on my beloved powershell 5.
* Apparently this file is important
* Create READMEITALIAN.md for Italian users
Added Italian translation for the README file, detailing the functionality and usage of WinUtil.
* Fix formatting in READMEITALIAN.md
* Rename READMEITALIAN.md to .github/READMEITALIAN.md
* Added Delivery Optimization tweak to Standard Tweaks preset
* Added Delivery Optimization tweak to Standard Tweaks preset and Advanced preset to match Gabi PR
* Update CONTRIBUTING.md
* updated the apps page and pics
* updated tweaks tab pic
* updated features page with pic
* updated update page with pic
* update win 11 page with pic
* update pics for app page
* deleted old pics
* fix favicon from not showing
* added forums link in help
* Update hugo.toml
* updated title screen pic and added it to the main screen
* Update _index.md
* added the recommended section to the user guild tweeks
* Update _index.md
* added the new advance preset
* clean up pages
* fix links
* fixed wikipedia link
* Update _index.md
* Less radical removal of apps
* Moving some applications to Selfhosted category
* Some more chess-boxing
* Document section is too small
* TG forks are too niche
* Floorp should be good
* feat: Add new multimedia tools and update existing application entries in applications.json
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Add checkbox for known issues acknowledgment
Some people do not check the link
* typo fix
Updated checkbox type to checkboxes in bug report template.
* :zombie_sound:
* :zombie_sound_2:
* AAAAAAAAAAAAAAA
* I'm tired of testing commits
* :zombie_sound_1337:
Added a description to the read issues checkbox.
* my bad
* Revert "Revert "Simplfy Invoke-WPFUltimatePerformance.ps1 (#4319)" (#4333)"
This reverts commit 419b150220.
* Refactor Invoke-WPFUltimatePerformance function to use "ChrisTitus - Ultimate Power Plan" naming and improve power plan management
* add message for laptop users
* Remove activation of "ChrisTitus - Ultimate Power Plan" during setup
* Update Invoke-WPFUpdatesdisable.ps1 to not require a restart
* Update Invoke-WPFUpdatesdisable.ps1
* Update Invoke-WPFUpdatesdefault.ps1
* Merge branch 'ChrisTitusTech:main' into patch-9
* Update applications.json
* Remove Borderless Gaming
* Update UniGetUI code for their link and winget
---------
Co-authored-by: Vaso <92270244+VasoHD@users.noreply.github.com>
* cleaned up typo, fixes, grammatical and other related fixes (#2)
* typo in Lightshot app name
* remove trailing comma in applications.json
* consistent capitalization of Windows, WinGet - only user-facing text
- includes update to devdocs-generator.ps1, so docs for tweaks modifying registry will have `Windows settings` rather than `windows settings`
* various fixes for typos, style, punctuation and capitalization
* capitalize 'AM'
* Update README.md
change formatting for GitHub UI interaction form code format (` `) to bold md
Co-authored-by: Jay <65828559+Jay-o-Way@users.noreply.github.com>
* typos and wording in docs
---------
Co-authored-by: Jay <65828559+Jay-o-Way@users.noreply.github.com>
* Add Opera, OperaGX, Ruby and Lua entries
Update applications.json to include two new browser entries (Opera, OperaGX) and two development runtime entries (Ruby, Lua).
* Remove Opera and OperaGX from applications.json
Removed entries for Opera and OperaGX from applications list.
* - Added AI-Automation download section
- Fixed typo in CONTRIBUTING.md teminal -> terminal
* Move Cursor to Development
* Move AutoHotkey back to Utilities
* removed any windows 10 reference
* update links
* page clean up
* Update _index.md
* clean up getting started page
* clean up more pages
* Update faq.md
* Update _index.md
* more clean up
* updated theme to latest version
* updated tabs to the new way
* added missing frontmatter to pages
* updated hugo version
* edited the file structure
* revert back to old way
* Update _index.md
* fix typo and made sure it was upto date
* updated docs
* clean up navbar
* Update en.yaml
* initial usb fixes
* fix full button width
* Cleanup and Verbose output for copy
* expand ui and fix clean and reset
* Add minimal driver injection
* initial driver support
* fix verbage
* fix syntax error
* create log file on iso generation
* inject to boot.wim for install
* fix single driver install issues
* fix first run probs
* cleanup injection
* improve clean up
* Fix OSCDIMG output and cleanup comments
* Fix Scrollviewer in Status Log
* large drive support and change to Exfat
* Fix BOOT for older UEFI and Add error checks for small usb drives
* fix single usb drive error
* fix: cast selections to string to prevent PSCustomObject type issues
* fix(presets): clear existing selections before importing to replace state instead of merging
* refactor(impex): warn user when exporting empty selections or importing empty config
* Tab creation
* scaffold outline for the iso tab
* autounattended creation
* inital modification success
* iso save success
* cleanup and iso improvements
* fix startmenu on new 26h2
* remove old first startup
* Fix run for use
* fix unapproved verb
* Keep step 4 output expanded
* update auto-merge
* Cleanup
* remove out-null and trailing whitespace
* explain modify and creator button
* fix scroll to end
* remove workflow change
* fix home updates
* Tab creation
* scaffold outline for the iso tab
* autounattended creation
* inital modification success
* iso save success
* cleanup and iso improvements
* fix startmenu on new 26h2
* remove old first startup
* Fix run for use
* fix unapproved verb
* Keep step 4 output expanded
* update auto-merge
* Cleanup
* remove out-null and trailing whitespace
* explain modify and creator button
* fix scroll to end
* remove workflow change
* updated workflow
* changed the commit message
* fixed spacing in copyright
i will notice these issues before committing in future lol
* Update devdocs-generator.md
* Update Invoke-WPFSystemRepair.ps1
* Update Invoke-WPFSystemRepair.ps1
* add chkdsk back in to tell users if there disk is broken
* Merge branch 'Update-Invoke-WPFSystemRepair' of https://github.com/gabinun/winutil into pr/GabiNun/4043
* add doc
* updated the gen to add a blackline under the frontmatter and added .md file in the same location with breakdown on what the script does
* copyright fix.
found out the reason why it rendered correctly on my pc and not with site builder. it was because we use --minify for the site builder and i have not been using that on the local instance
* Update pre-release.yaml
* Update en.yaml
* feat: add support for importing and exporting WPFToggle checkbox states.
* feat: add export and import
* remove unnecessary buttons from tweaks tab
* Merge branch 'main' into feature/import-export
* Merge branch 'main' into feature/import-export
* updated theme to the latest version
* Update en.yaml
* removed all the order from the docs
* add the store link
* update homepage
* add filename and line number to all the code blocks and also removed pages
* auto pull the code from the json files
* Merge branch 'main' into winutil-new-features
* the script updated linenostart=
* Delete LaptopHibernation.md
* changed autolinks to now use frontmatter instead off #heading
* updated all docs with front matter names
* Update DisableLegacyRecovery.md
this was the same as EnableLegacyRecovery file
* made sure pages have got the corrects scripts on them
* Update default.md
updated the archetype default to make sure every new page had the title and description automatically on the front matter
* Create BraveDebloat.md
* added brave debloat link to tweaks.json
* Update tweaks.json
* Update tweaks.json
* Updated winutil website
add git ignore to not upload unnecessarily file. i have also updated microwin docs and added a copyright info to the footer
* Update _index.md
* Update KnownIssues.md
* Update links
update all the links for github to the corresponding pages. i have kept the original links aswell but commented out
* update hugo workflow to use version 0.147.0
* Update en.yaml
* update hugo toml to get rid off powered by
* Update docs.yaml
* Update KnownIssues.md
* Update KnownIssues.md
* Update KnownIssues.md
* Update compatibility note for MicroWin and Ventoy
* removed quad 9 dns
* fixed all the incorrect code block in markdown file
* Replace hardcoded page lists with auto-discovery shortcode
Created a new shortcode at docs/layouts/shortcodes/autolinks.html. This enables auto-discovery when creating new Markdown files, streamlining the workflow for future documentation updates.
* updated os requirements
* Fix: retry password prompt on failure to prevent script halting
* Update Invoke-WPFInstall.ps1
* format fix
* fix: change RealTimeIsUniversal to QWord for correct UTC time sync
---------
Co-authored-by: Chris Titus <contact@christitus.com>
Co-authored-by: Chris Titus Tech <dfm.titus@gmail.com>
* New reporting tool
* Why did we EVER need to load the component store?
* Up the execution policy for default PWSH sessions
This is required to run the diagnostics script, and any script that either we create here, or the user creates later. At least we don't go too wild and use unrestricted... we use something more "safe"
* Force Panther Setup instead of MoSetup
This will increase reliability and performance. Screw the Windows 8 installer, we're back with what was used on Windows 7!
Anyway, there are problems with the new installer:
1. It is slow at everything. Some people did benchmarks of both installers. MoSetup lost to Panther (ofc). Source: https://www.reddit.com/r/Windows11/comments/1kmjavl/i_made_a_small_test_comparing_which_one_installs/
2. It is unreliable. The "Install driver to show hardware" screen that appears in some systems AND in PXE/WDS for Server 2025 is possibly, and simply, due to Setup not being able to find the install image. From BlueBox.log in MoSetup:
...
2025-12-21 10:05:43: Creating path (with ACL): [X:\$WINDOWS.~BT]...
2025-12-21 10:05:43: Creating path: [X:\$WINDOWS.~BT\Sources]...
2025-12-21 10:05:43: CBootScenarioCtrl::PopulateWorkingDir: Install.wim/swm/esd was not found!
...
Other contributors in the CTT community stated similar unreliability with borked installs.
I'm pretty sure this change will benefit everyone. We'll see how long it lasts before Microsoft f's it up.
* Improve reporting tool
Display appx package dependency full names
* Rework ADK detection
* Add revamped detection for ISO creation
* File Explorer ain't broken anymore on 26200.7462
Those incompetent developers changed WindowsAppRuntime.CBS to WindowsAppRuntime.CBS.1.6 circa 10.0.26200.7462. No wonder why direct downloads were not causing this issue; they are still based on 10.0.26200.6584. The MCT, on the other hand...
* Patch maximum version boundary
Apparently they fixed that in November. Expanding the amd64_winappsdk-cbs-stable component manifest to a XML file reveals the dark secret:
<registryKeys>
<registryKey keyName="HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Appx\AppxAllUserStore\InboxApplications\Microsoft.WindowsAppRuntime.CBS.1.6_6000.653.2246.100_x64__8wekyb3d8bbwe">
<registryValue name="Path" valueType="REG_SZ" value="$(runtime.windows)\SystemApps\Microsoft.WindowsAppRuntime.CBS_8wekyb3d8bbwe\AppxManifest.xml" />
<securityDescriptor name="REGKEY_APPXALLUSERSTORE_SDDL" />
</registryKey>
<registryKey keyName="HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Appx\AppxAllUserStore\Config\Microsoft.WindowsAppRuntime.CBS.1.6_8wekyb3d8bbwe">
<registryValue name="SetupPhase" valueType="REG_DWORD" value="0x00000427" />
</registryKey>
<registryKey keyName="HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Appx\AppxAllUserStore\UpdatedApplications\Microsoft.WindowsAppRuntime.CBS.1.6_8wekyb3d8bbwe" />
</registryKeys>
This is not a problem in .6899 because we don't have amd64_winappsdk-cbs-stable, but a vnext counterpart. But, at this point, why bother checking with that? MCT will not bundle this update with the image!
* Default to showing file extensions
Apart from a security improvement (let's remember ILOVEYOU from 2000), it's also a QoL.
* Fix key for color modes
Color mode settings are saved per-user, not system-wide. So HKLM\SOFTWARE is not our solution. HKCU is, and is mapped to \Users\Default\NTUSER.DAT
* Move color mode from offline servicing to firstrun
* Drop build number by 100
* Update Invoke-Microwin.ps1 (#15)
* Revert "Update Invoke-Microwin.ps1 (#15)"
This reverts commit 88f8a3031b.
* Keep trying to commit and unmount images
* Consistent REG ADD /F /V...
Some issues happen with REG and strings if you put /f at the end... move it to the beginning, where it doesn't conflict with anything.
* Rework stub path reg value set
This works on both Windows 11 and Windows 10. It didn't work on Win10 before; it should work now
* Remove copy link step
We no longer do this
* Move Copy-Files to microwin folder
Only microwin calls this function; it's better if we place this script in that folder
* Add Create Bootable USB (#18)
* Add Create Bootable USB
* Apply suggestion from @CodingWonders
---------
Co-authored-by: CodingWonders <101426328+CodingWonders@users.noreply.github.com>
* Download ADK to get oscdimg if not to download on GitHub
If we don't download OSCDIMG from GitHub, because we now use ADK kits roots detection to get installed copies of the ADK and oscdimg, we just download the Deployment Tools. This is only 100 MB once fully installed, and removes the need to install Chocolatey.
One caveat is that, on 64-bit systems, the script will output "Could not find ADK" once. This is normal as it does checks on both regular SOFTWARE and WOW6432Node, and it's able to pick it on the latter. If it isn't found anywhere, that message will appear twice.
* Make indentation more consitent in bootable USB func.
* Initialize petoolspath variable
* Remove temporary adksetup on completion
* Fix whitespace
* Remove unnecessary comments and revamp admin check
* Revert "Add Create Bootable USB (#18)"
This reverts commit 64babfe986.
* Remove reporting tool creation
The reporting tool is now hosted on a separate repo. The script itself can be run anywhere, not just in microwin, so...
* Some formatting change here
* Remove copy to ventoy option
* Fix some more indents
* Add Description that ISO automatically removes Win11 Requirements
* Additional things
- WPBT done by defaults
- Skip Logon Animation
- Remove convert to ESD and Upgrade to Win11 as Win10 is no longer supported
* First attempt at OSCDIMG autodownload
* No more custom ScratchPaths!
Time to get rid of that mess and just use %TEMP%.
All of these minor changes were made on a Server 2K8R2 VM.
* Redetect ADK/OSCDIMG after autodownload
* Leave ADK reg query error to debug only
---------
Co-authored-by: Real-MullaC <callumjanes2007new+github@gmail.com>
* Delete WPFTweaksPowershell7 from tweaks.json
Removed WPFTweaksPowershell7 configuration for Windows Terminal.
* Delete functions/public/Invoke-WPFTweakPS7.ps1
* Update WPFTweaksRazerBlock's InvokeScript
* Format fix for WPFTweaksRazerBlock
* Update WPFTweaksRazerBlock
* Update WPFTweaksRazerBlock
* Update WPFTweaksRazerBlock
* Better format for WPFTweaksRazerBlock's InvokeScript
* Better format for WPFTweaksRazerBlock's InvokeScript
* Fomat fix on WPFTweaksRazerBlock
* Update WPFTweaksRemoveHome to use powershell
* Fix WPFTweaksRemoveGallery format
* Format fix for WPFTweaksRemoveHome
* Update tweaks.json
* fix my f up
* Update tweaks.json to use registry modifications
Replaced InvokeScript and UndoScript with registry modifications for removing Home from Explorer and setting This PC as default.
* fix missing comma from twitch chat
* [Tweaks] Conditionally determine when to use sc and Set-Service
* Clean up comments in Set-WinUtilService.ps1
Removed comments explaining the handling of auto delayed start for PWSH 5.
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* Update tweaks.json
* Fix
* Final Fix
* Added comments to WPFTweaksBlockAdobeNet
* Syntax change for WPFTweaksBlockAdobeNet
* Removed double \ from WPFTweaksBlockAdobeNet
* Added back double \ for WPFTweaksBlockAdobeNet
* Syntax fix for WPFTweaksBlockAdobeNet
* Syntax fix for WPFTweaksBlockAdobeNet again
* Fix for WPFTweaksBlockAdobeNet
* Merge branch 'ChrisTitusTech:main' into Update-WPFTweaksBlockAdobeNet
* Rename m to M
* Update tweaks.json
* Update tweaks.json
* Update tweaks.json
* Merge branch 'ChrisTitusTech:main' into Typo-Fix
* Merge branch 'ChrisTitusTech:main' into Typo-Fix
* Extra space
* From Tweaks to Toggle
* Merge branch 'ChrisTitusTech:main' into Typo-Fix
* Added Proton Authenticator to applications.json
Proton Authenticator is a popular open source 2fa app from proton.
* Update name in applications.json
---------
Co-authored-by: CyberSphinx <202843220+CyberSphonx@users.noreply.github.com>
The Invoke-WinUtilTweaks function was using the '-contains' operator on a string variable to check for toggle-type tweaks. This operator is intended for collections (arrays), not for substring matching within a string, leading to incorrect logic flow.
This caused an issue where selecting one tweak (e.g., WPFTweaksRightClickMenu) could erroneously trigger the action of another (e.g., WPFTweaksDisableCrossDeviceResume).
This commit replaces the incorrect '-contains' operator with the '-like' operator and appropriate wildcards ('*Toggle*'). This ensures that tweak types are identified correctly, resolving the bug and preventing unintended system modifications.
* feat: Add Beeper to Messaging applications
This commit adds the Beeper desktop application to the list of installable packages in the "Messaging" category.
The entry has been added to `config/applications.json` with the official download URL and the correct silent installation arguments.
Fixes#3608
* Fix job failure: ensure excluded directory exists before processing
This commit updates the Invoke-Preprocessing function to prevent workflow failures caused by missing excluded directories.
Previously, the script would attempt to recursively list files in excluded paths, resulting in an error if a directory did not exist.
The updated logic checks if the excluded path refers to a directory (ends with a backslash) and creates it if necessary before proceeding. This avoids "Cannot find path" errors and ensures smoother preprocessing, especially for jobs that depend on directory existence for exclusion logic.
No changes are made for excluded files or wildcard patterns.
* [Applications] DISM utility changes, app description fixes
- NTLite has been added to the list of apps to give the user some choice
- Both DISMTools and NTLite have been moved to a new section so they can be identified more easily by what they do, and because the former is not a tool made by either Microsoft or Sysinternals. The former now has its description pulled from WinGet (and summarized using Copilot)
- Em-dashes in some app descriptions have been replaced with semicolons to avoid question marks in tooltips
* Change category from 'DISM Utilities' to 'Microsoft Tools'
---------
Co-authored-by: Chris Titus <contact@christitus.com>
* [Enhance] Configure all apps view in start menu
To keep look consistent with older Win11
* [Enhance] Additional Start menu settings
* [MicroWin] Change Write-Host to Write-Debug on debug lines. (#13)
* Add a resolution to scripts being disabled (#14)
* [MicroWin] Change Write-Host to Write-Debug on debug lines.
* Add a resolution to scripts being disabled
* Add skip first logon anim option
* Unrelated: indentation fixes from compile script
* Some little touches to the first-run script
---------
Co-authored-by: Real-MullaC <callumjanes2007new+github@gmail.com>
* Test the latest changes to WinUtil by running the pre-release and reporting issues you are encountering to help us continually improve WinUtil!
#### **Run the latest pre-release**
```ps1
irm https://christitus.com/windev | iex
```
!!! bug "Keep in mind"
```ps1
irm https://christitus.com/windev|iex
```
This is a pre-release and should be treated as such. It exists for developers to test the utility and report or fix bugs before they get added to the stable release. Don't use it in production!
> [!CAUTION]
> **Keep in mind:** This is a pre-release and should be treated as such. It exists for developers to test the utility and report or fix bugs before they get added to the stable release. Don't use it in production!
## Issues
@@ -21,19 +21,19 @@
* Pull requests are now handled directly on the **MAIN branch**. This was done since we can now select specific releases to launch via releases in GitHub.
* If you're doing code changes, then you can submit a PR to `main` branch, but I am very selective about these.
* If you're doing code changes, then you can submit a PR to the `main` branch.
!!! warning "Important"
Do not use a code formatter, make massive amounts of line changes, or make multiple feature changes. EACH FEATURE CHANGE SHOULD BE IT'S OWN PULL REQUEST!
> [!IMPORTANT]
> Do not use a code formatter, make massive amounts of line changes, or make multiple feature changes. EACH FEATURE CHANGE SHOULD BE ITS OWN PULL REQUEST!
>
> Do not open a pull request that adds support for other languages to WinUtil for now, until we decide how we want to move forward with language support.
* When creating pull requests, it is essential to thoroughly document all changes made. This includes, but is not limited to, documenting any additions made to the `tweaks` section and corresponding `undo tweak`, so users are able to remove the newly added tweaks if necessary, and comprehensive documentation is required for all code changes. Document your changes and briefly explain why you made your changes in your Pull Request Description. Failure to adhere to this format may result in the denial of the pull request. Additionally, any code lacking sufficient documentation may also be denied.
* By following these guidelines, we can maintain a high standard of quality and ensure that the codebase remains organized and well-documented.
!!! note
When creating a function, please include "WPF" or "WinUtil" in the file name so it can be loaded into the runspace.
> [!NOTE]
> When creating a function, please include "WPF" or "WinUtil" in the file name so it can be loaded into the runspace.
While you can make your changes directly through the Web, we recommend cloning the repo to your device using the application GitHub Desktop (available in WinUtil) to test your fork easily.
> [!TIP]
> While you can make your changes directly through the Web, we recommend cloning the repo to your device using the application GitHub Desktop (available in WinUtil) to test your fork easily.
* Install GitHub Desktop if it is not already installed.
* Log in using the same GitHub account you used to fork WinUtil.
@@ -87,31 +84,35 @@ graph TD
### Testing your changes
* To test to see if your changes work as intended run following commands in a powershell teminal as admin:
* To test to see if your changes work as intended, run the following commands in a PowerShell terminal as admin:
* Change the directory where you are running the commands to the forked project.
*`cd {path to the folder with the compile.ps1}`
* Run the following command to compile and run WinUtil:
* After seeing that your changes work properly, feel free to commit the changes to the repository and make a PR. For help on that, follow the documentation below.
### Committing the changes
* Before committing your changes, please discard changes made to the `winutil.ps1` file, like the following:
* To make a PR on your repo under a new branch linking to the main branch, a button will show and say Preview and Create pull request. Click that button and fill in all the information that is provided on the template. Once all the information is filled in correctly, check your PR to make sure there is not a WinUtil.ps1 file attached to the PR. Once everything is good, make the PR and wait for Chris (the maintainer) to accept or deny your PR. Once it is accepted by Chris, you will be able to see your changes in the "/windev" build.
* To make a PR on your repo under a new branch linking to the main branch, a button will show and say Preview and Create pull request. Click that button and fill in all the information that is provided on the template. Once all the information is filled in correctly, check your PR to make sure there is no WinUtil.ps1 file attached to the PR. Once everything is good, make the PR and wait for Chris (the maintainer) to accept or deny your PR. Once it is accepted by Chris, you will be able to see your changes in the "/windev" build.
* If you do not see your feature in the main "/win" build, that is fine. All new changes go into the /windev build to make sure everything is working OK before going fully public.
* Congratulations! You just submitted your first PR. Thank you so much for contributing to WinUtil.
description:"Report a bug to help us identify and fix issues in the project."
title:"[Bug Report] - <your summary here>"
labels:["bug"]
body:
- type:markdown
attributes:
value:|
# 🐞 **Issue Report**
Thank you for taking the time to report an issue! Please provide as much detail as possible to help us address the problem efficiently.
## ⚠️ **IMPORTANT**
- 🛠️ **Supported environments only:** We only support Windows 11. Custom ISOs that are not made using Microwin are not supported.
- 💡 For general questions, use the [Discussions section](https://github.com/Christitustech/winutil/discussions) or join our Community-driven [Discord Server](https://discord.gg/RUbZUZyByQ).
- Remember, we only support Windows 11. If you encounter problems on Windows 10, please consider upgrading to Windows 11.
- For general questions, join our Community-driven [Discord Server](https://discord.gg/RUbZUZyByQ).
- type:checkboxes
id:read_issues
attributes:
label:⚙️ Issue Checklist
label:"I have read the known issues"
description:"You [better do](https://winutil.christitus.com/knownissues/), cause your issue can be already there"
options:
- label:I have read the guidelines.
- label:I checked for duplicate issues.
- label:I searched for existing discussions.
- label:I checked for an existing pull request that addresses this issue.
- label:Yes,I did
required:true
- type:input
id:winutil_version
attributes:
label:"Version of WinUtil"
description:"Provide a version that you are using when issue submitted (it can be found in right corner of app)"
validations:
required:true
- type:input
- type:dropdown
id:affected_part
attributes:
label:📜 What part of Winutil are you having issues with?
placeholder:"e.g., Microwin, Tweaks, etc."
label:What part of WinUtil are you having issues with?
options:
- Program Install Tab
- Tweaks Tab
- Config Tab
- Updates Tab
- Win11 Creator Tab
validations:
required:true
required:false
- type:textarea
id:issue_description
attributes:
label:📝 Provide a clear and concise description of the issue.
label:"Description of the issue"
description:Provide a clear and concise description of the issue.
validations:
required:true
- type:textarea
id:steps_to_reproduce
id:tweaks_applied
attributes:
label:🔄 Steps to reproduce the issue.
placeholder:"e.g., Step 1: ..., Step 2: ..."
label:"List of Applied Tweaks"
description:List the tweaks you applied before the issue occurred.
validations:
required:true
required:false
- type:textarea
id:error_output
attributes:
label:❌ Paste the full error output (if available).
placeholder:"Include any relevant logs or error messages."
- type:textarea
id:additional_context
attributes:
label:🖼️ Additional context.
placeholder:"Include screenshots, code blocks (use triple backticks ```), or any other relevant information."
validations:
required:false
label:Paste the full error output (if available) or Screenshot or Video.
description:"If you're willing to share the whole log, please provide an external link to text-sharing service, i.e. Pastebin"
placeholder:"Include any relevant logs or error messages. Keep any sensitive info out of the presented log"
description:"Suggest a new feature or improvement for the project."
title:"[Feature Request] - <your summary here>"
labels:["enhancement"]
body:
@@ -11,47 +12,12 @@ body:
## ⚠️ **IMPORTANT**
- 🛠️ **Supported environments only:** We only support Windows 11.
- 💡 For general questions, use the [Discussions section](https://github.com/Christitustech/winutil/discussions) or join our Community-driven [Discord Server](https://discord.gg/RUbZUZyByQ).
- type:checkboxes
attributes:
label:⚙️ Issue Checklist
options:
- label:I have read the guidelines.
- label:I checked for duplicate issues.
- label:I searched for existing discussions.
- label:I checked for an existing pull request that addresses this request.
validations:
required:true
- type:textarea
id:problem_statement
attributes:
label:❓ Is your feature request related to a problem?
placeholder:"Provide a clear and concise description of the issue you're facing. Example: 'I'm always frustrated when [...]'"
validations:
required:false
- 💡 For general questions, use the [Discussions section](https://github.com/ChrisTitusTech/winutil/discussions) or join our Community-driven [Discord Server](https://discord.gg/RUbZUZyByQ).
- type:textarea
id:proposed_solution
attributes:
label:💡 Describe the solution you'd like
placeholder:"Provide a clear and concise description of what you want to happen."
placeholder:"Provide a clear and concise description."
validations:
required:true
- type:textarea
id:alternatives
attributes:
label:🔄 Describe alternatives you've considered
placeholder:"Provide details on any alternative solutions or features you've thought about."
validations:
required:false
- type:textarea
id:additional_context
attributes:
label:🖼️ Additional context
placeholder:"Include screenshots, code blocks (use triple backticks ```), or any other relevant information."
<!--Before you make this PR have you followed the docs here? - https://christitustech.github.io/winutil/contribute/ -->
<!--Before you make this PR have you followed the docs here? - https://winutil.christitus.com/contributing/ -->
<!--Documentation is auto-generated from configs - no manual documentation updates needed -->
## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Documentation update
- [ ] Refactoring
- [ ] Hotfix
- [ ] Security patch
- [ ] Refactor
- [ ] UI/UX improvement
<!-- This automatically adds labels to your PR based on the selections above. -->
## Description
<!--[Provide a detailed explanation of the changes you have made. Include the reasons behind these changes and any relevant context. Link any related issues.]-->
## Testing
<!--[Detail the testing you have performed to ensure that these changes function as intended. Include information about any added tests.]-->
## Impact
<!--[Discuss the impact of your changes on the project. This might include effects on performance, new dependencies, or changes in behaviour.]-->
<!--[What does this PR do? Provide Screenshots when possible.]-->
## Issue related to PR
<!--[What issue/discussion is related to this PR (if any)]-->
<!--[List any ISSUES this is related to as it AUTO-CLOSES Them!]-->
- Resolves #
## Additional Information
<!--[Any additional information that reviewers should be aware of.]-->
## Checklist
- [ ] My code adheres to the coding and style guidelines of the project.
- [ ] I have performed a self-review of my own code.
- [ ] I have commented my code, particularly in hard-to-understand areas.
- [ ] I have made corresponding changes to the documentation.
- [ ] My changes generate no errors/warnings/merge conflicts.
Questa utility è una raccolta di attività Windows che eseguo personalmente su ogni sistema che utilizzo. È progettata per snellire le *installazioni*, rimuovere i componenti superflui tramite *ottimizzazioni*, risolvere problemi tramite la *configurazione*, e riparare *aggiornamenti* di Windows. Sono estremamente selettivo riguardo ai contributi per mantenere questo progetto pulito ed efficiente.
Winutil deve essere eseguito con privilegi di amministratore, poiché apporta modifiche all'intero sistema. Per farlo, avvia PowerShell come amministratore. Ecco alcuni modi per procedere:
1.**Metodo del menu di Start:**
- Fai clic con il tasto destro sul menu Start.
- Scegli "Windows PowerShell (esegui come Amministratore)" (per Windows 10) o "Terminale (esegui come Amministratore)" (per Windows 11).
2.**Metodo tramite ricerca:**
- Premi il tasto Windows.
- Digita "PowerShell" o "Terminal" (per Windows 11).
- Premi `Ctrl + Shift + Invio` oppure fai clic con il tasto destro e seleziona "Esegui come amministratore" per avviarlo con privilegi elevati.
### Comando di avvio
#### Branch stabile (Consigliato)
```ps1
irm "https://christitus.com/win"|iex
```
#### Branch Sviluppatore
```ps1
irm "https://christitus.com/windev"|iex
```
### Automazione
Winutil supporta anche preset predefiniti che applicano automaticamente configurazioni comuni:
In caso di problemi, consulta i [Problemi noti](https://winutil.christitus.com/knownissues/) o [Apri una segnalazione](https://github.com/ChrisTitusTech/winutil/issues)
## 🎓 Documentazione
### [Documentazione ufficiale di WinUtil](https://winutil.christitus.com/)
### [Tutorial su YouTube](https://www.youtube.com/watch?v=6UQZ5oQg8XA)
### [Articolo su ChrisTitus.com](https://christitus.com/windows-tool/)
## 🛠️ Build & Sviluppo
> [!NOTE]
> Winutil è uno script piuttosto esteso, per questo è suddiviso in più file che vengono combinati in un unico file `.ps1` tramite un compilatore personalizzato. Questo rende la manutenzione del progetto molto più semplice.
Ottieni una copia del codice sorgente. Puoi farlo tramite l'interfaccia di GitHub (**Code** > **Download ZIP**), oppure clonando (scaricando) la repo tramite git.
Se git è installato, esegui i seguenti comandi in una finestra PowerShell per clonare e accedere alla directory del progetto:
Per compilare il progetto, esegui lo script di compilazione in una finestra PowerShell (i permessi di amministratore NON sono richiesti):
```ps1
.\Compile.ps1
```
Troverai un nuovo file chiamato `winutil.ps1`, creato dallo script `Compile.ps1`. Ora puoi eseguirlo come amministratore e apparirà una nuova finestra. Goditi la tua versione compilata di WinUtil :)
> [!TIP]
> Per ulteriori informazioni sull'utilizzo di WinUtil e su come contribuire allo sviluppo, ti invitiamo a leggere le [Linee guida per i contributi](https://winutil.christitus.com/contributing/). Se non sai da dove iniziare o hai domande, puoi chiedere sul nostro [Server Discord della community](https://discord.gg/RUbZUZyByQ); i membri attivi del progetto risponderanno appena possibile.
## 💖 Supporto
- Per sostenere il progetto moralmente e mentalmente, non dimenticare di lasciare una ⭐️!
- Wrapper EXE a 10$ su https://www.cttstore.com/windows-toolbox
## 💖 Sponsor
Questi sono gli sponsor che aiutano a mantenere vivo il progetto con contributi mensili.
If you find a security issue please make post it in the issues tab. If you think it should be private you can email me at contact@christitus.com.
If you find a security issue, please post it in the Issues tab. If you think it should be private, you can email me at contact@christitus.com.
For immediate response check out our discord server @ [](https://discord.gg/RUbZUZyByQ)
For immediate response check out our Discord server:
Drop-in operating instructions for coding agents. Read this file before every task.
**Working code only. Finish the job. Plausibility is not correctness.**
`SPEC.md` in the repository root is the project contract — read it for what WinUtil is and how it's architected. This file covers how to work on it.
## 0. Non-Negotiables
These rules override everything else in this file when in conflict:
1.**Do not edit `winutil.ps1` directly.** It is generated build output (see SPEC.md's Build Model). Change source files and compile.
2.**Do not commit `winutil.ps1`.** It is ignored locally and generated by GitHub Actions for releases.
3.**Never touch `docs/src/content/docs/code-reference/tweaks/` or `docs/src/content/docs/code-reference/features/`.** Both are auto-generated (see SPEC.md's Docs Site). Edit the source JSON (`config/tweaks.json`, `config/feature.json`) or the relevant PowerShell function file instead. Other hand-written pages under `code-reference/` (e.g. `architecture.mdx`) are not touched by the generator and may be edited directly.
4.**Never fabricate.** Do not invent file paths, function names, command output, test results, commit hashes, or API behavior. Read the file or run the command.
5.**Disagree when the premise is wrong.** Say what is wrong before acting on it.
6.**Stop when genuinely ambiguous.** If two interpretations would produce materially different diffs, ask before editing.
7.**Touch only what the task requires.** No drive-by refactors, formatting sweeps, or unrelated cleanup.
8.**Verify before saying done.** A plausible-looking diff is not proof.
## 1. Key Commands
- Compile:
```powershell
.\Compile.ps1
```
- Compile and run GUI:
```powershell
.\Compile.ps1 -Run
```
- Install the supported Pester version (one-time). `-SkipPublisherCheck` is required because Windows ships an inbox Pester 3.4.0 that is catalog-signed, and PowerShell Gallery's Pester 5.8.0 is Authenticode-signed — `Install-Module` refuses the upgrade without it. This does not skip download integrity (still HTTPS + NuGet package hash verification); `-Repository PSGallery` pins the trusted source explicitly rather than relying on whatever repositories happen to be registered:
- Run Script Analyzer with project settings when available. If a locally compiled `winutil.ps1` exists, delete it first — `lint/PSScriptAnalyser.ps1` only excludes rules, not files, so `-Recurse` would also lint the generated script and produce noise against line numbers that don't map to any source file:
- Docs site dev server (run from `docs/`; see Section 2 for why this goes through Docker):
```powershell
docker compose up winutil-astro
```
- Docs site production build (run from `docs/`):
```powershell
docker compose run --rm winutil-astro npm run build
```
Prefer the narrowest useful verification while iterating. Use the full relevant check before finishing.
## 2. Dependency Installs, Builds, And Dev Servers
Given the current wave of npm/pnpm/yarn supply-chain worms (malicious postinstall/preinstall scripts, credential-stealing packages): **never run npm/pnpm/yarn/npx directly on the host, full stop.** The docs site (`docs/`) is the only npm-based project in this repo; always run its tooling inside Docker via `docs/Dockerfile` and `docs/docker-compose.yml` (service `winutil-astro`).
- Never run `npm install`, `npm run <script>`, `npx <pkg>`, `pnpm`, or `yarn` directly on the host shell in `docs/`. Use `docker compose run --rm winutil-astro <command>` / `docker compose up winutil-astro` instead (see Section 1 for the exact commands).
- If a task needs a new docs dependency, add it to `docs/package.json` yourself, then rebuild the image and drop the `node_modules` volume so it repopulates from the new image (run from `docs/`): `docker compose build winutil-astro`, then `docker compose down -v`. Docker only seeds a named volume from the image the first time it's created, so a plain rebuild silently leaves the old `node_modules` in place. Don't install packages on the host, even temporarily, "just to check something."
- If Docker isn't available on the host, propose the install command for the current OS and wait for confirmation before running it — don't fall back to running npm on the host instead. If the daemon just isn't running (Docker is installed but not started), tell the user rather than trying to start it yourself.
- Treat any `postinstall`/`preinstall` lifecycle script in a new dependency as worth flagging to the user before installing — summarize what it does.
- Don't put real secrets anywhere under `docs/`. `docs/.dockerignore` only trims what `docker build` copies into the image — it does not affect the `docker compose` bind mount, which exposes the entire `docs/` directory (including any `.env` file) inside the container for every dev/build/preview command (see the next bullet). There is no "keep it out unless mounted" middle ground here.
- The container mounts `docs/` as a volume, so file edits on the host are reflected inside the container immediately — no rebuild needed for normal code changes, only when `docs/package.json`/`docs/package-lock.json` change (see the rebuild-and-drop-volume steps above).
- This Docker requirement is specific to `docs/`. PowerShell tooling runs directly on the host per Section 1. The Python project under `tools/title-screen/` runs with uv as documented in its README.
## 3. Source Of Truth
For changes that affect the compiled WinUtil script, make them only in the source files described in SPEC.md's Repository Layout — never in `winutil.ps1` itself. If behavior changes require the compiled script to change, update the source files and run `.\Compile.ps1` only to verify generation.
This scoping applies to compiled-script behavior only. Repository metadata — `AGENTS.md`, `SPEC.md`, `CLAUDE.md`/`GEMINI.md`/`.github/copilot-instructions.md`, `.github/workflows/`, and the root `.gitignore` — is edited directly when a task requires it, per the other sections of this file.
## 4. Before Editing
- State the plan in one or two sentences before editing. For non-trivial work, include the verification you intend to run.
- Read the files you will touch and the files that call them.
- Match existing patterns even when a different greenfield design would be cleaner.
- Surface assumptions when they affect behavior, compatibility, or user data.
- If two approaches have meaningful tradeoffs, name them before choosing. Trivial tasks can proceed directly.
## 5. Coding Guidelines
- Prefer the minimum code that solves the stated problem.
- Keep PowerShell functions in one function file when practical, with the file name matching the primary function name.
- Use approved PowerShell verb-noun names and follow the existing `WPF` / `WinUtil` naming conventions; keep UI event handler names aligned with XAML element names per SPEC.md's UI And Event Contract.
- Use `$sync` for shared state and UI references, consistent with SPEC.md's Runtime Model.
- Update WPF controls through the UI dispatcher when running work in a background runspace.
- Keep config-driven features in JSON when they fit the existing schema instead of hard-coding lists in PowerShell; follow SPEC.md's Configuration Contract for required fields and key-renaming rules.
- Preserve undo/original-state data for tweaks so users can reverse changes.
- Do not add abstractions, configurability, hooks, or "future extensibility" unless the task needs them now.
- Clean up orphans created by your own changes, such as unused variables or functions made obsolete by the edit.
- Avoid broad formatting-only edits, especially in JSON config files, XAML, docs, and generated output.
## 6. Runtime And Safety Rules
- WinUtil performs system-level Windows changes; treat registry, services, AppX removal, package manager, Windows Update, ISO, and unattended setup changes as high-risk (see SPEC.md's Safety Requirements).
- Prefer existing helper functions for WinGet, Chocolatey, registry, services, progress, and UI updates.
- Keep tweaks reversible where the schema supports it by including original values or original states.
- Never modify a user's original ISO in-place; follow existing copy/mount/export patterns.
- Avoid storing credentials, secrets, or machine-specific paths in repo files.
- Preserve logging and user feedback patterns for long-running or destructive operations.
## 7. Surgical Changes
- Do not improve adjacent code, comments, formatting, imports, or docs unless required.
- Do not refactor working code because you are already in the file.
- Do not delete pre-existing dead code unless asked; mention it in the summary if relevant.
- Keep diffs reviewable. Every changed line should trace to the user's request.
- If a change starts spreading across unrelated areas, pause and reassess the plan.
## 8. Verification
Define success in terms that can be checked, then check it.
- For compile/build changes, run `.\Compile.ps1`.
- For GUI behavior changes, run `.\Compile.ps1 -Run` when practical and verify the affected path manually.
- For config changes, run the compile check and relevant Pester tests.
- For function changes, run the relevant Pester tests or add/update focused tests when practical.
- For docs-only changes, proofread the changed files and skip runtime tests unless docs generation is affected.
- Read command output. Do not report tests as passing unless they actually passed.
- If verification fails, fix the cause rather than weakening the test.
If a check cannot be run, say exactly why and what residual risk remains. See SPEC.md's Testing And CI for what GitHub Actions runs on every push.
## 9. Generated Files And Git Hygiene
- Treat local `winutil.ps1` changes as disposable compile output.
- Never stage or commit `winutil.ps1`, `binary/`, or anything else ignored by the root `.gitignore` or `docs/.gitignore` — read those files rather than assuming. `docs/public/` is tracked source for static assets, not generated output.
- `docs/src/assets/branding/title-screen.png` is a tracked generated asset. Do not edit it manually. Update `tools/title-screen/` or run the title-screen workflow.
- Do not remove `.gitignore` rules that keep generated artifacts out of Git.
- Before finishing, check `git status --short` and separate your changes from pre-existing user changes.
- Do not revert user changes unless explicitly asked.
- Commit messages, when requested, should be descriptive: short subject under 72 characters, body explaining why when needed.
- When committing, split changes into small, logical commits rather than one large commit, so each commit's diff is reviewable as a single group of related changes.
## 10. Documentation Expectations
- Update `docs/src/content/docs/guides/` when user-facing behavior changes.
- Update `docs/src/content/docs/code-reference/architecture.mdx` and other hand-written developer docs when architecture, build flow, config schema, or contribution workflow changes — but never hand-edit the auto-generated `code-reference/tweaks/` or `code-reference/features/` subfolders (see Non-Negotiables).
- Keep sidebar entries in `docs/astro.config.mjs` in sync with page slugs (see SPEC.md's Docs Site).
- Keep README changes brief and high-level.
- Put detailed user and developer documentation under `docs/`.
- Keep SPEC.md aligned with project/architecture changes, and this file aligned with process changes.
## 11. Communication Style
- Be direct and concise. Start with the answer or action.
- No flattery, filler, ceremonial closings, or fake certainty.
- Use bullets only when they improve scanning.
- Report what changed, how it was verified, and anything not done.
- If the user asks for a review, lead with findings and file/line references.
## 12. When To Ask
Ask before proceeding when:
- The request has two plausible interpretations and the choice materially changes behavior or files touched.
- The change affects release generation, generated artifacts, migrations, or high-risk Windows behavior in a way the user did not specify.
- You need credentials, secrets, production resources, or access you do not have.
- The user's stated goal conflicts with the literal request.
Proceed without asking when:
- The task is trivial and reversible.
- Ambiguity can be resolved by reading the code or running a local command.
- The user already answered the question in this session.
## 13. Project Learnings
When the user corrects an agent approach, add or tighten one concrete rule here before ending the session. Keep this section short and prune rules that no longer matter.
- Keep `winutil.ps1` generated-only: change source files, compile to verify, and never stage the generated script.
- Keep WinUtil runtime logging in the existing timestamped `%LocalAppData%\winutil\logs\winutil_*.log` session file; do not create a separate root `winutil.log`.
- Import Pester 5.8.0 before running tests so `Invoke-Pester -Output Detailed -CI` does not resolve to Windows' inbox Pester 3.4.0.
- Keep package install/uninstall process launches simple unless explicitly requested; do not add a separate stdout/stderr process logging helper for winget or Chocolatey.
- When the active log file is owned by `Start-Transcript`, do not call `Add-Content` against that file; write to host output so the transcript captures the line in the same log file without recording a terminating-error diagnostic.
- Keep UI helpers such as `Invoke-WPFUIThread` and `Step-WinUtilJob` safe to call without a window; the `-Preset` and `-Config` paths run the workflows before the form is created and before PresentationCore is loaded. Ask `Test-WinUtilUIAlive` rather than writing the `$sync.Form` / dispatcher / `HasShutdownStarted` check out by hand.
- Put long operations on the job layer with `Start-WinUtilJob` and report from them with `Step-WinUtilJob`; a job body must not set the busy flag, print its own banner, or carry its own try/catch/finally around the interface. `Invoke-WPFRunspace` directly is for fire-and-forget work that is not a job.
- Drain interface work that nobody is waiting for through `Start-WinUtilBackgroundQueue`; do not hand-roll another dequeue-and-re-post pump.
- Values a posted scriptblock needs travel as the dispatcher's argument or through `-Parameters`, never captured from the caller: a plain block resolves them when the dispatcher gets to it, and `GetNewClosure` binds command lookup to a copied scope. For the same reason, prefer a compiled `[action]` over `Invoke-WPFUIThread -Async` on hot re-posting paths, which marshals its body as text and recompiles it per post.
- Diagnostic scaffolding does not ship. Measure with it, then delete it.
- Have each Pester file load the assemblies and dot-source the functions it needs; several passed only because an earlier file in alphabetical order happened to load them.
- Log install/uninstall package names and package-manager IDs before queuing background runspace work; do not rely on runspace host output for the package identity.
- For Win11 Creator, start each new ISO modification in a fresh `WinUtil_Win11ISO_*` temp directory; existing-work detection is only for resuming/exporting already modified media.
- For Win11 Creator driver injection, inject storage controllers (`SCSIAdapter` / `HDC`) into `boot.wim` index 2 with DISM, not `$WinpeDriver$`. Keep `install.wim` on its own per-package `/Add-Driver` retry loop. For each image, add each root package folder with its own `/Add-Driver /Recurse` so a single bad driver cannot fail the rest, and skip any folder whose ancestor is already in the set, since that ancestor's `/Recurse` covers it. Warn per failure and commit only when at least one package was added; when none were, warn and discard rather than throwing, so the run still produces an ISO. The discard in the cleanup block carries both orphaned mounts and that intentional zero-added case; keep it. Do not export editions or run unrelated WIM cleanup, and reject damaged metadata before ISO export. Use `-LiteralPath` for driver export paths, since `%TEMP%` can contain wildcard characters.
- For Script Analyzer cleanup, fix actionable source warnings first and do not globally suppress accepted convention warnings such as plural names, `ShouldProcess` on UI helpers, `$global:sync`, or compile-time cross-file false positives.
- For DNS DHCP reset, keep the cmdlet reset and explicitly set IPv4 and IPv6 DNS source to DHCP.
- Public pull-request diffs may be sent to configured external review services without a separate privacy approval; do not block the review loop on upload authorization for this public repository.
- Keep install-tab favicon loading overlapped with app-entry rendering; do not replace native WPF loading with a deferred second phase unless visible completion time is proven no slower than `main`.
This utility is a compilation of Windows tasks I perform on each Windows system I use. It is meant to streamline *installs*, debloat with *tweaks*, troubleshoot with *config*, and fix Windows *updates*. I am extremely picky about any contributions to keep this project clean and efficient.
A curated compilation of Windows system tasks streamline **installs**, debloat with **tweaks**, troubleshoot with **config**, and configure **Windows updates**. Run it fresh on every new Windows install.
Winutil must be run in Admin mode because it performs system-wide tweaks. To achieve this, run PowerShell as an administrator. Here are a few ways to do it:
---
1.**Start menu Method:**
- Right-click on the start menu.
- Choose "Windows PowerShell (Admin)" (for Windows 10) or "Terminal (Admin)" (for Windows 11).
## Quick Start
2.**Search and Launch Method:**
- Press the Windows key.
- Type "PowerShell" or "Terminal" (for Windows 11).
- Press `Ctrl + Shift + Enter` or Right-click and choose "Run as administrator" to launch it with administrator privileges.
> **WinUtil must be run as Administrator** because it performs system-wide changes.
### Launch Command
#### Stable Branch (Recommended)
Open PowerShell or Terminal as admin, then run:
**Stable Branch (recommended)**
```ps1
irm "https://christitus.com/win"|iex
```
#### Dev Branch
```ps1
irm "https://christitus.com/windev"|iex
irm https://christitus.com/win|iex
```
If you have Issues, refer to [Known Issues](https://winutil.christitus.com/knownissues/)
## 🎓 Documentation
> [!NOTE]
> To contribute to the documentation, please visit [WinUtil Docs Repo](https://github.com/Chris-Titus-Docs/winutil-docs) for more info.
### [WinUtil Official Documentation](https://winutil.christitus.com/)
> Winutil is a relatively large script, so it's split into multiple files which're combined into a single `.ps1` file using a custom compiler. This makes maintaining the project a lot easier.
Get a copy of the source code, this can be done using GitHub UI (`Code -> Download ZIP`), or by cloning (downloading) the repo using git.
If git is installed, run the following commands under a PowerShell window to clone and move into project's directory:
You'll see a new file named `winutil.ps1`, which's created by `Compile.ps1` script, now you can run it as admin and a new window will popup, enjoy your own compiled version of WinUtil :)
| Preset | Description |
|--------|-------------|
| `Standard` | Balanced defaults for most users |
| `Minimal` | Minimal changes to suit every user |
| `Advanced` | Deep tweaks for power users |
> [!TIP]
> For more info on using WinUtil and how to develop for it, please consider reading [the Contribution Guidelines](https://winutil.christitus.com/contributing/), if you don't know where to start, or have questions, you can ask over on our [Discord Community Server](https://discord.gg/RUbZUZyByQ) and active project members will answer when they can.
Project contract for WinUtil — what the project is, how it's built, and how it runs. Written for anyone, human or AI, who needs to understand the project itself.
`AGENTS.md` in the repository root points here for these facts, and separately covers how an agent should behave while working in this repo. This file does not change based on who's reading it.
## Project Context
WinUtil is a Windows PowerShell utility with a WPF interface. The repository is maintained as modular source, but the distributed artifact is one compiled PowerShell script.
### Stack
- Language: Windows PowerShell / PowerShell.
- UI: WPF via `xaml/inputXML.xaml`.
- Configuration: JSON files under `config/`.
- Tests: Pester tests under `pester/`.
- Lint: PowerShell Script Analyzer with settings in `lint/PSScriptAnalyser.ps1`.
- Docs: Astro + Starlight site under `docs/`, built independently of `Compile.ps1` (its own `package.json`/`node_modules`).
- Release artifact: generated root `winutil.ps1`.
### Repository Layout
-`Compile.ps1`: build script that creates `winutil.ps1`.
-`scripts/start.ps1`: startup/bootstrap segment used at the beginning of the compiled script.
-`scripts/main.ps1`: main entrypoint appended at the end of the compiled script.
-`tools/title-screen/`: uv project that captures WinUtil's Light and Dark themes and generates the title-screen composite.
-`docs/`: Astro + Starlight documentation site, with its own `package.json` and build independent of `Compile.ps1`.
-`winutil.ps1`: ignored generated build artifact.
## Goals
- Provide a single-script Windows utility that can be launched from PowerShell.
- Keep development modular enough for contributors to work on functions, config, UI, docs, and tooling independently.
- Make install, tweak, feature, repair, update, and ISO workflows discoverable from the WPF UI.
- Keep common lists and options declarative in JSON config where possible.
- Preserve a repeatable compile process so local builds and GitHub Actions builds produce the distributable script from the same inputs.
## Non-Goals
-`winutil.ps1` is not hand-maintained.
- The project is not structured as a PowerShell module at runtime.
- The GUI is not a separate packaged desktop application in this repository's normal release path.
- Generated files should not be reviewed as source changes.
## Build Model
`Compile.ps1` combines the repository sources into `winutil.ps1` in this order:
1. Read `scripts/start.ps1` and replace `#{replaceme}` with the current `yy.MM.dd` build date.
2. Append every file under `functions/` recursively.
3. Convert each `config/*.json` file into embedded `$sync.configs` objects.
4. Special-case `config/applications.json` so keys receive the `WPFInstall` prefix in compiled config.
5. Embed `xaml/inputXML.xaml` into `$inputXML`.
6. Embed `tools/autounattend.xml` into `$WinUtilAutounattendXml`.
7. Append `scripts/main.ps1`.
8. Write the result to root `winutil.ps1`.
Because the final script is concatenated, code cannot rely on runtime module imports or source-relative dot-sourcing unless the compiled script will also contain the required code/data.
## Runtime Model
- WinUtil runs in PowerShell on Windows and uses WPF for the UI.
- Shared mutable state is stored in `$sync`, including configs, UI element references, runspace state, selections, and progress.
- Long-running operations use runspaces or existing async patterns so the UI remains responsive.
- UI updates from background work are dispatched back to the WPF UI thread.
- Declarative features such as apps, tweaks, presets, DNS providers, and navigation stay in `config/*.json` unless code is required.
## UI And Event Contract
- UI layout lives in `xaml/inputXML.xaml`.
- Named WPF controls are discovered and stored in `$sync`.
- Button/action wiring follows a naming convention: an element named like `WPFThingButton` maps to a function named like `Invoke-WPFThingButton`.
## Configuration Contract
- Config files must remain valid JSON and compile cleanly through `ConvertFrom-Json`.
-`config/dns.json` opts unfiltered providers into Fastest selection with `BenchmarkEligible: true`; missing or false values exclude a provider from the TCP latency benchmark.
-`config/applications.json` defines installable applications; each entry includes the fields expected by tests and UI code, such as package manager IDs, category, display content, description, and link.
-`config/tweaks.json` defines Windows tweaks; registry and service changes include original values or original states when applicable so undo workflows can restore user systems.
- Preset and navigation files reference valid config keys. Renaming a config key requires updating all presets, UI references, docs, and code paths together.
## Safety Requirements
- Registry, service, package manager, Windows Update, AppX removal, and ISO operations affect the host system and are treated as high-risk.
- Tweak changes include undo metadata when the schema supports it, so changes stay reversible.
- ISO workflows never modify the user's original ISO file; they work on copied/mounted content.
## Docs Site (Astro)
-`docs/` is an Astro + Starlight site, independent of `Compile.ps1`'s build (its own `package.json`/`node_modules`, deployed via the `docs.yaml` GitHub Actions workflow to GitHub Pages).
- Pages live under `docs/src/content/docs/` (`.mdx`), organized into `guides/`, `code-reference/`, plus top-level pages like `faq.mdx`, `knownissues.mdx`, `contributing.mdx`, `index.mdx`.
-`docs/src/content/docs/code-reference/tweaks/` and `.../features/` are auto-generated by `tools/devdocs-generator.ps1` from `config/tweaks.json`/`config/feature.json` and the relevant PowerShell function files. Other pages under `code-reference/` (e.g. `architecture.mdx`) are hand-written and untouched by the generator.
- Sidebar entries in `docs/astro.config.mjs` must match actual page slugs under `docs/src/content/docs/`.
-`docs/public/` is tracked source for static assets (favicons, etc.), not generated output. Generated/ignored paths are listed in `docs/.gitignore` (`dist/`, `.astro/`, `node_modules/`, local env files).
-`docs/src/assets/branding/title-screen.png` is a tracked generated image used by the repository README and docs homepage. Its raw Light and Dark captures are temporary.
-`docs/Dockerfile` and `docs/docker-compose.yml` (service `winutil-astro`) containerize the site's npm tooling; see AGENTS.md's Dependency Installs, Builds, And Dev Servers for why and how agents must use them instead of running npm on the host.
## Testing And CI
-`.\Compile.ps1` verifies the compiler can generate `winutil.ps1`.
-`.\Compile.ps1 -Run` compiles and launches the generated utility for manual GUI verification.
- Pester 5.8.0 runs the suite under `pester/*.Tests.ps1`. GitHub Actions (`unittests.yaml`) installs Pester 5.8.0 fresh and runs with `-CI`, which produces `testResults.xml` and exits non-zero on failure.
- GitHub Actions also runs PowerShell Script Analyzer with `lint/PSScriptAnalyser.ps1` on every push.
- The generated `winutil.ps1` may appear locally after compile. It remains ignored build output (see root `.gitignore`) and must not be committed.
- The manually triggered title-screen workflow compiles WinUtil from `main` and opens an image-only pull request when the generated composite changes. These pull requests require manual review. Failed runs retain diagnostics for 14 days.
## Release Artifact
GitHub Actions is responsible for producing the release `winutil.ps1` from repository sources. A release is considered valid only if the generated script came from the compile process, not from direct manual edits to `winutil.ps1`.
"Description":"Allows users to submit bug reports, feature suggestions, and diagnostic data directly to Microsoft.",
"Panel":"0",
"PackageId":"Microsoft.WindowsFeedbackHub",
"StoreId":"9NBLGGH4R32N"
},
"WPFAppxMicrosoft_GetHelp":{
"Category":"Microsoft Apps",
"Content":"Get Help",
"Description":"Provides access to automated troubleshooting guides, support documentation, and direct Microsoft customer assistance.",
"Panel":"0",
"PackageId":"Microsoft.GetHelp",
"StoreId":"9PKDZBMV1H3T"
},
"WPFAppxMicrosoft_OutlookForWindows":{
"Category":"Microsoft Apps",
"Content":"Outlook for Windows",
"Description":"Provides modern email management, calendar scheduling, and contact organization features.",
"Panel":"0",
"PackageId":"Microsoft.OutlookForWindows",
"StoreId":"9NRX63209R7B"
},
"WPFAppxMSTeams":{
"Category":"Microsoft Apps",
"Content":"Microsoft Teams",
"Description":"Facilitates instant messaging, video conferencing, file sharing, and workspace collaboration.",
"Panel":"0",
"PackageId":"MSTeams",
"StoreId":"XP8BT8DW290MPQ"
},
"WPFAppxClipchamp_Clipchamp":{
"Category":"Utilities & Productivity",
"Content":"Clipchamp",
"Description":"Provides a user-friendly video editor with built-in templates, effects, and timeline editing tools.",
"Panel":"0",
"PackageId":"Clipchamp.Clipchamp",
"StoreId":"9P1J8S7CCWWT"
},
"WPFAppxMicrosoft_MicrosoftOfficeHub":{
"Category":"Microsoft Apps",
"Content":"Microsoft 365",
"Description":"Serves as a centralized launcher and dashboard for accessing cloud-based Microsoft 365 apps and recent documents.",
"Panel":"0",
"PackageId":"Microsoft.MicrosoftOfficeHub",
"StoreId":"9WZDNCRD29V9"
},
"WPFAppxMicrosoft_ZuneMusic":{
"Category":"Utilities & Productivity",
"Content":"Media Player",
"Description":"Plays local audio and video files with modern playlist management and casting capabilities.",
"Panel":"0",
"PackageId":"Microsoft.ZuneMusic",
"StoreId":"9WZDNCRFJ3PT"
},
"WPFAppxMicrosoft_BingSearch":{
"Category":"Bing & Web Services",
"Content":"Bing Search",
"Description":"Integrates Microsoft Bing search capabilities and web services directly into the operating system.",
"Panel":"1",
"PackageId":"Microsoft.BingSearch",
"StoreId":"9NZBF4GT040C"
},
"WPFAppxMicrosoftCorporationII_QuickAssist":{
"Category":"Utilities & Productivity",
"Content":"Quick Assist",
"Description":"Enables secure remote technical support and screen sharing over an internet connection.",
"Panel":"0",
"PackageId":"MicrosoftCorporationII.QuickAssist",
"StoreId":"9P7BP5VNWKX5"
},
"WPFAppxMicrosoft_WindowsDevHome":{
"Category":"Developer Tools",
"Content":"Dev Home",
"Description":"Provides a specialized dashboard for software developer environment setups, repository syncing, and hardware widgets.",
"Panel":"1",
"PackageId":"Microsoft.Windows.DevHome",
"StoreId":"9N8MHTPHNGVV"
},
"WPFAppxMicrosoft_WindowsCrossDevice":{
"Category":"Microsoft Ecosystem",
"Content":"Mobile Devices",
"Description":"Manages system-level background connectivity with paired mobile devices. Removing this may disable cross-device features such as phone screen mirroring, file transfer, and mobile hotspot handoff integrated into Windows Settings.",
"Panel":"0",
"PackageId":"MicrosoftWindows.CrossDevice",
"StoreId":"9NTXGKQ8P7N0"
},
"WPFAppxMicrosoft_Todos":{
"Category":"Utilities & Productivity",
"Content":"To Do",
"Description":"Creates, tracks, and synchronizes personal tasks, smart lists, and daily reminders.",
"Panel":"0",
"PackageId":"Microsoft.Todos",
"StoreId":"9NBLGGH5R558"
},
"WPFAppxMicrosoft_PowerAutomateDesktop":{
"Category":"Developer Tools",
"Content":"Power Automate",
"Description":"Automates repetitive workflows and desktop tasks using low-code visual scripting.",
"Panel":"1",
"PackageId":"Microsoft.PowerAutomateDesktop",
"StoreId":"9NFTCH6J7FHV"
},
"WPFAppxMicrosoft_YourPhone":{
"Category":"Microsoft Ecosystem",
"Content":"Phone Link",
"Description":"Synchronizes text messages, phone notifications, photos, and calls from a mobile device to the desktop.",
"Panel":"0",
"PackageId":"Microsoft.YourPhone",
"StoreId":"9NMPJ99VJBWV"
},
"WPFAppxMicrosoft_MicrosoftStickyNotes":{
"Category":"Utilities & Productivity",
"Content":"Sticky Notes",
"Description":"Creates quick, floating text notes on the desktop that automatically sync across devices.",
"Panel":"0",
"PackageId":"Microsoft.MicrosoftStickyNotes",
"StoreId":"9NBLGGH4QGHW"
},
"WPFAppxMicrosoft_WindowsSoundRecorder":{
"Category":"Utilities & Productivity",
"Content":"Sound Recorder",
"Description":"Records and trims live audio inputs with simple microphone adjustment controls.",
"Panel":"0",
"PackageId":"Microsoft.WindowsSoundRecorder",
"StoreId":"9WZDNCRFHWKN"
},
"WPFAppxMicrosoft_WindowsAlarms":{
"Category":"Utilities & Productivity",
"Content":"Clock",
"Description":"Features world clocks, alarms, countdown timers, stopwatches, and dedicated focus session tracking.",
"Panel":"0",
"PackageId":"Microsoft.WindowsAlarms",
"StoreId":"9WZDNCRFJ3PR"
},
"WPFAppxMicrosoft_Paint":{
"Category":"Utilities & Productivity",
"Content":"Paint",
"Description":"Provides built-in digital sketching, basic image editing, and pixel-level graphic manipulation tools.",
"Panel":"0",
"PackageId":"Microsoft.Paint",
"StoreId":"9PCFS5B6T72H"
},
"WPFAppxMicrosoft_WindowsNotepad":{
"Category":"Utilities & Productivity",
"Content":"Notepad",
"Description":"Provides a lightweight text editor with multi-tab support for plain text files and code snippets.",
"Panel":"0",
"PackageId":"Microsoft.WindowsNotepad",
"StoreId":"9MSMLRH6LZF3"
},
"WPFAppxMicrosoft_ScreenSketch":{
"Category":"Utilities & Productivity",
"Content":"Snipping Tool",
"Description":"Captures screenshots or screen recordings with built-in markup, image cropping, and optical character recognition (OCR).",
"Panel":"0",
"PackageId":"Microsoft.ScreenSketch",
"StoreId":"9MZ95KL8MR0L"
},
"WPFAppxMicrosoft_Copilot":{
"Category":"Bing & Web Services",
"Content":"Copilot",
"Description":"Launches the Microsoft AI companion for contextual answers, creative writing assistance, and intelligent web search.",
"Panel":"1",
"PackageId":"Microsoft.Copilot",
"StoreId":"9NHT9RB2F4HD"
},
"WPFAppxMicrosoft_WindowsCalculator":{
"Category":"Utilities & Productivity",
"Content":"Calculator",
"Description":"Performs standard arithmetic, scientific operations, programming calculations, and unit conversions.",
"Panel":"0",
"PackageId":"Microsoft.WindowsCalculator",
"StoreId":"9WZDNCRFHVN5"
},
"WPFAppxMicrosoft_WindowsCamera":{
"Category":"Utilities & Productivity",
"Content":"Camera",
"Description":"Captures photographs and records video files via connected webcams or imaging hardware.",
"Panel":"0",
"PackageId":"Microsoft.WindowsCamera",
"StoreId":"9WZDNCRFJBBG"
},
"WPFAppxMicrosoft_WindowsPhotos":{
"Category":"Utilities & Productivity",
"Content":"Photos",
"Description":"Organizes, views, and crops local images with basic color adjustment and album creation tools.",
"Panel":"0",
"PackageId":"Microsoft.Windows.Photos",
"StoreId":"9WZDNCRFJBH4"
},
"WPFAppxMicrosoft_BingNews":{
"Category":"Bing & Web Services",
"Content":"News",
"Description":"Aggregates breaking news headlines, personalized article feeds, and world current events.",
"Panel":"1",
"PackageId":"Microsoft.BingNews",
"StoreId":"9WZDNCRFHVFW"
},
"WPFAppxMicrosoft_BingWeather":{
"Category":"Bing & Web Services",
"Content":"Weather",
"Description":"Displays local real-time weather tracking, radar maps, and historical meteorological forecasts.",
"Panel":"1",
"PackageId":"Microsoft.BingWeather",
"StoreId":"9WZDNCRFJ3Q2"
},
"WPFAppxMicrosoft_GamingApp":{
"Category":"Xbox & Gaming",
"Content":"Xbox App",
"Description":"Serves as the primary gaming library manager, social community interface, and PC Game Pass dashboard.",
"Panel":"1",
"PackageId":"Microsoft.GamingApp",
"StoreId":"9MV0B5HZVK9Z"
},
"WPFAppxMicrosoft_XboxGamingOverlay":{
"Category":"Xbox & Gaming",
"Content":"Xbox Game Bar",
"Description":"Provides customizable in-game status widgets, audio balancing sliders, system monitoring tools, and gameplay recording.",
"Panel":"1",
"PackageId":"Microsoft.XboxGamingOverlay",
"StoreId":"9NZKPSTSNW4P"
},
"WPFAppxMicrosoft_XboxIdentityProvider":{
"Category":"Xbox & Gaming",
"Content":"Xbox Identity Provider",
"Description":"Manages Xbox network user authentication and background account validation for connected titles. Warning: removing this may break Microsoft account sign-in for non-Xbox games and apps that rely on this authentication pipeline.",
"Panel":"1",
"PackageId":"Microsoft.XboxIdentityProvider",
"StoreId":"9WZDNCRD1HKW"
},
"WPFAppxMicrosoft_XboxSpeechToTextOverlay":{
"Category":"Xbox & Gaming",
"Content":"Xbox Speech To Text Overlay",
"Description":"Provides system-level live accessibility captions and voice-to-text translation for gaming chat networks.",
"Panel":"1",
"PackageId":"Microsoft.XboxSpeechToTextOverlay"
},
"WPFAppxMicrosoft_Xbox_TCUI":{
"Category":"Xbox & Gaming",
"Content":"Xbox TCUI",
"Description":"Provides core account connection UI modules for single sign-on flows within game titles. Warning: removing this may break Microsoft account authentication in games and apps that do not otherwise require the Xbox app.",
"Panel":"1",
"PackageId":"Microsoft.Xbox.TCUI"
},
"WPFAppxMicrosoft_StartExperiencesApp":{
"Category":"Bing & Web Services",
"Content":"Start Experiences App",
"Description":"Powers the Windows Widgets board, delivering a personalized feed of news, weather, sports, and finance content.",
"Panel":"1",
"PackageId":"Microsoft.StartExperiencesApp",
"StoreId":"9PC1H9VN18CM"
},
"WPFAppxMicrosoft_MicrosoftSolitaireCollection":{
"Category":"Xbox & Gaming",
"Content":"Solitaire Collection",
"Description":"Bundles built-in card game modes including Klondike, Spider, FreeCell, Pyramid, and TriPeaks alongside daily challenges.",
"Description":".NET and .NET Framework is a developer platform made up of tools, programming languages, and libraries for building many different types of applications.",
"Description":"Replaces the default Windows NTP server (time.windows.com) with pool.ntp.org for improved time synchronization accuracy and reliability.",
"Content":"Windows Subsystem for Linux (WSL) - Enable",
"Description":"Windows Subsystem for Linux is an optional feature of Windows that allows Linux programs to run natively on Windows without the need for a separate virtual machine or dual booting.",
"Description":"Windows Sandbox is a lightweight virtual machine that provides a temporary desktop environment to safely run applications and programs in isolation.",
"category":"Features",
"panel":"1",
"Order":"a021_",
"Description":"Windows Sandbox is a lightweight virtual machine that provides a temporary desktop environment to safely run applications and programs in isolation.",
[](https://starlight.astro.build)
Documentation site for [WinUtil](https://github.com/ChrisTitusTech/winutil), built with [Astro](https://astro.build) and [Starlight](https://starlight.astro.build). Served at [winutil.christitus.com](https://winutil.christitus.com/).
## 🚀 Project Structure
```
.
├── public/
├── src/
│ ├── assets/
│ ├── components/
│ ├── content/
│ │ └── docs/
│ ├── styles/
│ └── content.config.ts
├── astro.config.mjs
├── docker-compose.yml
├── Dockerfile
├── package.json
└── tsconfig.json
```
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
Images can be added to `src/assets/` and embedded in Markdown with a relative link.
Static assets, like favicons, can be placed in the `public/` directory.
## 🧞 Commands
All commands run in a Docker container — there's no need to install Node or npm dependencies on your host. This is deliberate, not just convenience: npm/pnpm/yarn have seen a steady stream of supply-chain attacks (malicious `postinstall`/`preinstall` scripts, credential-stealing packages), so `npm install` and friends never run directly on a contributor's machine here. Note the container still has read-write access to this `docs/` directory (it's bind-mounted for live reload), so this only contains a compromised package to the project folder plus the container itself — it doesn't reach the rest of your host (SSH keys, other repos, cloud credentials elsewhere on disk). Don't keep real secrets in `docs/` as a result.
[Docker](https://www.docker.com/) (with Compose) is required — install Docker Desktop (or Docker Engine + the `docker compose` plugin on Linux) and make sure the daemon is running before using any of the commands below.
All commands are run from the `docs/` directory, from a terminal:
| `docker compose build` | Builds the dev image (needed after Dockerfile or dependency changes) |
| `docker compose up winutil-astro` | Starts local dev server at `localhost:4321` |
| `docker compose run --rm winutil-astro npm run build` | Build the production site to `./dist/` |
| `docker compose run --rm --service-ports winutil-astro npm run preview -- --host 0.0.0.0` | Preview the build locally, before deploying |
| `docker compose run --rm winutil-astro npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
| `docker compose down` | Stop and remove the dev container |
Source files are bind-mounted into the container, so edits on the host are picked up immediately by the dev server — no rebuild needed for normal content or code changes. After changing `package.json`, `package-lock.json`, or the `Dockerfile`, rebuild the image *and* drop the `node_modules` volume, since Docker only seeds a named volume from the image the first time it's created — a plain rebuild leaves the old `node_modules` in place:
```sh
docker compose build
docker compose down -v
docker compose up winutil-astro
```
The first `docker compose up` (or any command before an image exists) builds the image and runs `npm install` from scratch, which can take a few minutes. Subsequent runs reuse the cached image and start almost immediately.
## 👀 Want to learn more?
Check out [Starlight's docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
/* Footer layout: stacked meta row + pagination. */
footer {
flex-direction: column;
gap: 1.5rem;
}
.meta {
gap: 0.75rem 3rem;
justify-content: space-between;
flex-wrap: wrap;
margin-top: 3rem;
font-size: var(--sl-text-sm);
color: var(--sl-color-gray-3);
}
.meta > :global(p:only-child) {
margin-inline-start: auto;
}
/* "Built with Starlight" credit link. */
.kudos {
align-items: center;
gap: 0.5em;
margin: 1.5rem auto;
font-size: var(--sl-text-xs);
text-decoration: none;
color: var(--sl-color-gray-3);
}
.kudos:hover {
color: var(--sl-color-white);
}
}
@layer starlight.components {
.kudos :global(svg) {
color: var(--sl-color-orange);
}
}
/* Collapse the meta/pagination rows entirely when they have nothing in them (e.g. editUrl: false and no prev/next), instead of leaving an empty gap. */
footer .meta:empty,
footer :global(.pagination-links):empty {
display: none;
margin: 0;
}
/* Site-wide copyright line, matching the previous Hugo docs site's footer. The divider above it comes from Starlight's own .content-panel border. */
description: How WinUtil's GUI, functions, and JSON configuration files fit together, plus a deep dive into the Win11 Creator subsystem.
---
## Overview
WinUtil is a PowerShell-based Windows utility with a WPF (Windows Presentation Foundation) GUI. This document explains the architecture, code structure, and how different components work together.
**Naming Convention**: Functions start with `WPF` or `Winutil` to be loaded into the runspace.
#### 4. functions/private/
**Purpose**: Internal helper functions not directly called by users.
**Key Functions**:
- `Get-WinUtilVariables.ps1`: Retrieves UI element references
- `Install-WinUtilWinget.ps1`: Ensures WinGet is installed
- `Get-WinUtilCheckBoxes.ps1`: Gets checkbox states
- `Invoke-WinUtilCurrentSystem.ps1`: Gets system information
#### 5. config/*.json
**Purpose**: Define available applications, tweaks, and features declaratively.
**Files**:
- `applications.json`: Application definitions with WinGet/Choco IDs
- `tweaks.json`: Registry tweaks and their undo actions
- `feature.json`: Windows features that can be enabled/disabled
- `preset.json`: Predefined tweak combinations
- `dns.json`: DNS provider configurations
#### 6. xaml/inputXML.xaml
**Purpose**: WPF GUI layout and design.
**Structure**:
- Buttons with event handlers
- TextBoxes for input
- CheckBoxes for options
- ListBoxes for selections
## Win11 Creator Architecture
The **Win11 Creator** is a specialized subsystem within Winutil that creates customized Windows 11 ISOs. It operates independently of the main package installation and tweak system.
### Win11 Creator Components
**Core Functions** (`functions/private/`):
- `Invoke-WinUtilISO.ps1`: Main orchestrator containing ISO workflow and helper functions
- `Invoke-WinUtilISOBrowse`: ISO file selection dialog
- `Invoke-WinUtilISOMountAndVerify`: Validates and mounts ISO, verifies it is an official Windows 11 ISO
- `Invoke-WinUtilISOModify`: Launches modification in background runspace
- `Invoke-WinUtilISOExport`: Builds bootable ISO via `oscdimg.exe`
- `Invoke-WinUtilISOCheckExistingWork`: Recovers incomplete work sessions
- `Invoke-WinUtilISOCleanAndReset`: Cleans up temp directories and resets UI
- `Write-WinUtilISOLog`: Posts log messages to UI status box and session log
- `Set-WinUtilISOStep`: Controls wizard navigation state
- `Get-WinUtilEditionIdFromName`: Maps edition display names to setup edition IDs
- `Invoke-WinUtilRobocopy`: Copies files with exit code verification
- `Find-WinUtilOscdimg` / `Get-WinUtilOscdimgPath`: Locates or installs `oscdimg.exe`
- `Invoke-WinUtilISOUSB.ps1`: USB drive detection and formatting
- `Invoke-WinUtilISORefreshUSBDrives`: Enumerates USB drives
- `Get-WinUtilFreeDriveLetter`: Finds available drive letters
- `Invoke-WinUtilISOWriteUSB`: Formats USB drive as GPT/FAT32, splits WIM if needed, and copies files
- `Invoke-WinUtilISOScript.ps1`: Prepares setup media and customizations
- Stages AppX removal (19 bloatware packages) into `autounattend.xml` for first logon
- Applies 50+ registry tweaks during Windows Setup and first logon; removes scheduled tasks at first logon
- Triggers OneDrive uninstall during first logon
- Stages setup script fallbacks to `sources\$OEM$\$$\Setup\Scripts\`
- Pins selected edition in `autounattend.xml` and writes `sources\ei.cfg`
- Injects eligible current system drivers into WIM images if enabled (WIM mount is only used for driver servicing)
│ ├─ Inject storage drivers into boot.wim index 2 and eligible drivers into install.wim
│ └─ Validate WIM metadata before and after injection
├─ Dismount source ISO
└─ Report completion, enable export options
↓
Invoke-WinUtilISOExport (user chooses output)
├─ Option 1: Save as ISO
│ ├─ Build bootable ISO via oscdimg.exe (BIOS/UEFI dual-boot)
│ └─ Output: Win11_Modified_[date].iso (close to the source ISO size)
│
└─ Option 2: Write to USB
├─ Format USB as GPT
├─ Create single FAT32 partition (capped at 32 GB)
├─ Split install.wim into .swm files if > 3.8 GB
├─ Reject install.esd files of 4 GB or more
├─ Copy files via robocopy
└─ Output: Bootable USB (minimum 8 GB)
↓
Invoke-WinUtilISOCleanAndReset (optional)
├─ Dismount any open WIM mounts with discard
├─ Delete temp working directory (~10-15 GB)
└─ Reset UI to initial state
```
### Win11 Creator Validation & Safety
**ISO Validation**:
- Only accepts official Microsoft Windows 11 ISOs
- Validates presence of install.wim or install.esd
- Checks image metadata for "Windows 11" string
- Rejects custom, modified, or non-Windows 11 ISOs
**WIM Metadata Validation**:
- During driver injection, `Assert-WinUtilISOWimMetadata` validates critical fields (`Languages`, `Installation`, `Edition`, `ProductSuite`, `ProductType`) before and after WIM servicing
- Driver injection stops before export if the required metadata is missing or changes
- Without driver injection, WinUtil preserves the original installation image and skips WIM metadata validation
**Edition Pinning & Setup Fallback**:
- Writes `sources\ei.cfg` and removes `sources\PID.txt` so setup does not use mismatched OEM product keys
- Pins the selected edition index in `autounattend.xml` (`/IMAGE/INDEX`)
- Stages fallback setup scripts under `sources\$OEM$\$$\Setup\Scripts\` with `UseConfigurationSet` enabled
**Work Session Recovery**:
- Auto-detects incomplete work from previous sessions
- Allows resuming the export step without re-running selection and modification
- Prevents redundant modifications
**Modification Safety**:
- Windows PE and specialize set hardware bypass and setup safeguards; `WinUtil-PostInstall.ps1` applies additional registry changes at first logon
- Original ISO never modified; only working copy
- Logged to the WinUtil session log and the live UI status panel
- DISM handles image dismount with automatic cleanup and discard on error
### Win11 Creator Registry Tweaks
The `Invoke-WinUtilISOScript` function applies **50+ registry tweaks** during setup and first logon:
**Hardware Bypass**:
- TPM 2.0 check bypass
- Secure Boot requirement bypass
- CPU compatibility bypass
- RAM requirement bypass
- Storage check bypass
**Privacy & Telemetry**:
- Disable advertising ID
- Disable tailored experiences
- Disable input personalization
- Disable speech online privacy
- Disable cloud content suggestions
- Disable app suggestion subscriptions
- Remove CEIP, Appraiser, WaaSMedic, etc.
**OOBE & Setup**:
- Enable local account setup
- Skip Microsoft account requirement
- Dark mode by default
- Empty taskbar and Start Menu
**Post-Setup Installations**:
- Prevent DevHome auto-installation
- Prevent new Outlook Mail app installation
- Prevent Teams auto-installation
**System Features**:
- Disable BitLocker and device encryption
- Disable Chat icon from the Taskbar
- Disable OneDrive folder backup
- Disable Copilot
- Disable Windows Update during OOBE (re-enabled at first login)
### Driver Injection Feature
**Optional Enhancement**: When enabled, exports all drivers from the running system and injects them into:
- `install.wim` (main OS image), excluding stale duplicates
- `boot.wim` index 2 (Windows Setup PE environment), storage controllers only (`SCSIAdapter` / `HDC`)
**Use Case**: Enables offline installation on systems with missing drivers.
description: "Disables Advanced Boot Options screen that lets you start Windows in advanced troubleshooting modes."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFFeatureDisableLegacyRecovery": {
"Content": "Legacy F8 Boot Recovery - Disable",
"Description": "Disables Advanced Boot Options screen that lets you start Windows in advanced troubleshooting modes.",
description: "Enables Advanced Boot Options screen that lets you start Windows in advanced troubleshooting modes."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFFeatureEnableLegacyRecovery": {
"Content": "Legacy F8 Boot Recovery - Enable",
"Description": "Enables Advanced Boot Options screen that lets you start Windows in advanced troubleshooting modes.",
description: "Enables daily registry backup, previously disabled by Microsoft in Windows 10 1803."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
description: "Windows Sandbox is a lightweight virtual machine that provides a temporary desktop environment to safely run applications and programs in isolation."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFFeaturesSandbox": {
"Content": "Windows Sandbox - Enable",
"Description": "Windows Sandbox is a lightweight virtual machine that provides a temporary desktop environment to safely run applications and programs in isolation.",
description: ".NET and .NET Framework is a developer platform made up of tools, programming languages, and libraries for building many different types of applications."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
"Description": ".NET and .NET Framework is a developer platform made up of tools, programming languages, and libraries for building many different types of applications.",
description: "Hyper-V is a hardware virtualization product developed by Microsoft that allows users to create and manage virtual machines."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFFeatureshyperv": {
"Content": "Hyper-V - Enable",
"Description": "Hyper-V is a hardware virtualization product developed by Microsoft that allows users to create and manage virtual machines.",
title: "Legacy Media Components (WMP, DirectPlay) - Enable"
description: "Enables legacy programs from previous versions of Windows."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFFeatureslegacymedia": {
"Content": "Legacy Media Components (WMP, DirectPlay) - Enable",
"Description": "Enables legacy programs from previous versions of Windows.",
description: "Network File System (NFS) is a mechanism for storing files on a network."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFFeaturenfs": {
"Content": "Network File System (NFS) - Enable",
"Description": "Network File System (NFS) is a mechanism for storing files on a network.",
title: "Windows Subsystem for Linux (WSL) - Enable"
description: "Windows Subsystem for Linux is an optional feature of Windows that allows Linux programs to run natively on Windows without the need for a separate virtual machine or dual booting."
editUrl: false
---
:::note
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFFeaturewsl": {
"Content": "Windows Subsystem for Linux (WSL) - Enable",
"Description": "Windows Subsystem for Linux is an optional feature of Windows that allows Linux programs to run natively on Windows without the need for a separate virtual machine or dual booting.",
This page is generated from [`functions/public/Invoke-WPFPanelAutologin.ps1`](https://github.com/ChrisTitusTech/winutil/blob/main/functions/public/Invoke-WPFPanelAutologin.ps1). Do not edit this page directly.
This page is generated from [`functions/public/Invoke-WPFSystemRepair.ps1`](https://github.com/ChrisTitusTech/winutil/blob/main/functions/public/Invoke-WPFSystemRepair.ps1). Do not edit this page directly.
description: "Replaces the default Windows NTP server (time.windows.com) with pool.ntp.org for improved time synchronization accuracy and reliability."
editUrl: false
---
:::note
This page is generated from [`functions/public/Invoke-WPFFixesNTPPool.ps1`](https://github.com/ChrisTitusTech/winutil/blob/main/functions/public/Invoke-WPFFixesNTPPool.ps1). Do not edit this page directly.
This page is generated from [`functions/public/Invoke-WPFFixesNetwork.ps1`](https://github.com/ChrisTitusTech/winutil/blob/main/functions/public/Invoke-WPFFixesNetwork.ps1). Do not edit this page directly.
This page is generated from [`functions/public/Invoke-WPFFixesUpdate.ps1`](https://github.com/ChrisTitusTech/winutil/blob/main/functions/public/Invoke-WPFFixesUpdate.ps1). Do not edit this page directly.
Performs various tasks in an attempt to repair Windows Update
.DESCRIPTION
1. (Aggressive Only) Scans the system for corruption using the Invoke-WPFSystemRepair function
2. Stops Windows Update Services
3. Remove the QMGR Data file, which stores BITS jobs
4. (Aggressive Only) Renames the DataStore and CatRoot2 folders
DataStore - Contains the Windows Update History and Log Files
CatRoot2 - Contains the Signatures for Windows Update Packages
5. Renames the Windows Update Download Folder
6. Deletes the Windows Update Log
7. (Aggressive Only) Resets the Security Descriptors on the Windows Update Services
8. Reregisters the BITS and Windows Update DLLs
9. Removes the WSUS client settings
10. Resets WinSock
11. Gets and deletes all BITS jobs
12. Sets the startup type of the Windows Update Services then starts them
13. Forces Windows Update to check for updates
.PARAMETER Aggressive
If specified, the script will take additional steps to repair Windows Update that are more dangerous, take a significant amount of time, or are generally unnecessary
#>
param($Aggressive = $false)
Write-Progress -Id 0 -Activity "Repairing Windows Update" -PercentComplete 0
This page is generated from [`functions/public/Invoke-WPFFixesWinget.ps1`](https://github.com/ChrisTitusTech/winutil/blob/main/functions/public/Invoke-WPFFixesWinget.ps1). Do not edit this page directly.
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
This page is generated from [`config/feature.json`](https://github.com/ChrisTitusTech/winutil/blob/main/config/feature.json). Do not edit this page directly.
:::
```json title="config/feature.json"
"WPFPanelPower": {
"Content": "Power Panel",
"category": "Legacy Windows Panels",
"panel": "2",
"Type": "Button",
"ButtonWidth": "300",
"InvokeScript": [
"powercfg.cpl"
],
}
```
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Omar
