Bring the docs in line with 3.4.0

README.md

@@ -57,7 +57,7 @@ WinSwift provides a dedicated, non-destructive low-latency optimization stack de
 | **Anti-Cheat Compatibility** | **100% Compatible** (Vanguard, EAC, BattlEye, FACEIT) | Often broken due to stripped security modules | Mixed (some scripts break Hyper-V / VBS dependencies) |
 | **Windows Update Support** | **Full Support** (Standard cumulative updates work normally) | Broken or permanently disabled | Supported |
 | **Execution Architecture** | Native PowerShell 5.1 in-memory execution | Modified ISO reinstall required (data wipe) | External package managers and third-party CLIs |
-| **Rollback & Safety** | Automatic state backup snapshot with instant `-Revert` | Impossible without full OS reinstallation | Manual registry inspection required |
+| **Rollback & Safety** | Pre-run snapshot, automatic rollback on a failed apply, and per-feature `-Undo` | Impossible without full OS reinstallation | Manual registry inspection required |
 | **Security Posture** | Retains core Defender & SmartScreen by default | Defender stripped completely (malware risk) | Toggles vary |
 | **Verification Auditing** | Built-in `-Verify` and `-VerifyProfile` audit engine | No automated state verification | None |
 
@@ -109,7 +109,7 @@ WinSwift implements a three-stage execution safety model before and after applyi
 
 ### Stage 1 - Pre-Execution Snapshot
 
-Before any registry key is written, WinSwift captures a point-in-time backup of all registry paths scheduled for modification. The backup is written to a timestamped `.reg` export under `%TEMP%\WinSwift_Backup_<timestamp>`. If `-SkipRegistryBackup` is not specified, this step is mandatory and blocks execution on failure. A System Restore point is created before any of the four high-impact custom modules run.
+Before any registry key is written, WinSwift captures a point-in-time backup of all registry paths scheduled for modification. The backup is written to `Backups\WinSwift-RegistryBackup-<timestamp>.json`. If `-SkipRegistryBackup` is not specified, this step is mandatory and blocks execution on failure. A System Restore point is created before any of the four high-impact custom modules run.
 
 ### Stage 2 - Feature Apply Engine
 
@@ -125,6 +125,28 @@ After applying changes, or at any time using `-Verify` or `-VerifyProfile`, WinS
 
 Exit code `0` signals full compliance. Exit code `2` signals drift, an unsupported feature state, or a verification failure. This enables automated rollout pipelines and endpoint compliance auditing without manual inspection.
 
+### Stage 4 - Automatic Rollback
+
+If the apply phase fails, WinSwift restores the Stage 1 backup on its own rather than leaving a half-applied system. A registry import failure triggers the restore; the run then stops without attempting any undo work, because undo on top of a restored or partially changed system makes the final state harder to reason about.
+
+An app removal failure does **not** trigger rollback. A registry backup cannot reinstall a removed Appx package, so restoring the registry there would report a recovery that did not happen while the apps stay gone.
+
+Pass `-NoAutoRollback` to leave a failed run in place for inspection. Note that `-SkipRegistryBackup` removes the material rollback depends on, so the two are mutually exclusive in practice.
+
+Rollback outcome, the condition that triggered it, and the backup file path are recorded in the run summary written to `%TEMP%\WinSwift_RunSummary_<timestamp>.json`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success, or verification fully compliant |
+| `1` | Generic failure |
+| `2` | Verification noncompliant, unsupported, or failed |
+| `3` | Apply failed and was rolled back cleanly |
+| `4` | Apply failed and the rollback itself also failed |
+
+Exit `4` is the only outcome that needs someone at the machine. A fleet script can retry on `3` and alert on `4`.
+
 ## ⚙️ How It Works
 
 WinSwift operates entirely in memory using standard PowerShell protocols. It takes a backup snapshot of your state, parses your configuration, and surgically removes or alters OS components.
@@ -144,8 +166,10 @@ flowchart TD
     F --> I[Module: The AI Purge]
     F --> J[Module: Performance & Gaming]
 
-    G & H & I & J --> K[Commit Changes]
-    K --> L[Generate Summary Report]
+    G & H & I & J --> K{Apply Succeeded?}
+    K -- Yes --> L[Commit Changes]
+    K -- No --> M[Restore Snapshot]
+    L & M --> N[Generate Summary Report]
 ```
 
 ---
@@ -245,9 +269,17 @@ Check an exported configuration or preset:
 powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\WinSwift.ps1 -VerifyProfile .\Config\DefaultSettings.json -Silent
 ```
 
-Treat exit code `0` as compliant. Treat exit code `2` as noncompliant, unsupported, or failed verification. Review each result to identify registry values or Appx packages that remain outside the requested state.
+Treat exit code `0` as compliant. Treat exit code `2` as noncompliant, unsupported, or failed verification. Review each result to identify registry values or Appx packages that remain outside the requested state. See the exit code table above for the rollback codes `3` and `4`.
+
+Revert applied features without opening the GUI:
+
+```PowerShell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\WinSwift.ps1 -CLI -Silent -Undo DisableTelemetry,DisableCopilot
+```
+
+`-Undo` accepts the 87 of 112 features that declare an undo registry file or have a dedicated undo routine. Anything else is rejected rather than reported as reverted.
 
-Use `-SkipExplorerRestart` to defer the Explorer restart. Use `-SkipRegistryBackup` only in controlled disposable environments.
+Use `-SkipExplorerRestart` to defer the Explorer restart. Use `-NoAutoRollback` to keep a failed run in place for inspection. Use `-SkipRegistryBackup` only in controlled disposable environments, and note that it disables automatic rollback.
 
 ---
 

SECURITY.md

@@ -8,7 +8,8 @@ WinSwift is a modular Windows 11 optimization and debloating toolkit. Because Wi
 
 | Version | Supported | Status |
 |---|---|---|
-| `3.3.x` | Yes | Active production release supporting Windows 11 23H2, 24H2, and 25H2 |
+| `3.4.x` | Yes | Active production release supporting Windows 11 23H2, 24H2, and 25H2 |
+| `3.3.x` | No | Superseded. Contains an elevation guard that did not stop a non-elevated run, fixed in 3.4.0 |
 | `< 3.3.0` | No | Legacy baseline |
 
 ---
@@ -32,3 +33,9 @@ Report vulnerabilities to `security@bios-system.net`. Do not open public GitHub
 
 ### 4. Desired-State Verification
 - Integrated `-Verify` and `-VerifyProfile` audit modes allow administrators to inspect system state and verify drift with exit code `2` before applying changes.
+
+### 5. Elevation Enforcement
+- The administrator check stops the run before any runtime module loads. Versions before 3.4.0 printed the warning but continued into the apply pipeline, because `exit` inside a dot-sourced script does not terminate the caller. A non-elevated run could reach registry imports and scheduled task changes and fail partway through, leaving a partially applied system.
+
+### 6. Automatic Rollback
+- A failed apply restores the registry backup taken before the run instead of leaving the system half-changed. Exit code `3` reports a clean rollback, `4` reports a rollback that itself failed and names the backup file for manual recovery.

UPSTREAM.md

@@ -148,7 +148,7 @@ Upstream does not provide OOBE bypass tooling or silent software installation. W
 | **24H2 AI purge depth** | Granular non-destructive GPO suppression | Basic Copilot removal | Recall and Copilot toggle | Granular service disables | Total binary removal (risk of shell crashes) |
 | **Windows Update lifecycle** | Fully intact | Fully intact | Intact (unless update service killed) | Fully intact | Broken or frozen |
 | **Post-apply verification** | Built-in -Verify and -VerifyProfile engine with exit code 2 | None | None | None | None |
-| **Rollback capability** | Automatic registry snapshot + System Restore + -Revert | Basic registry backup | System Restore only | Detailed restore script | Impossible without OS reinstall |
+| **Rollback capability** | Pre-run snapshot, automatic rollback on failed apply, System Restore, per-feature `-Undo` | Basic registry backup | System Restore only | Detailed restore script | Impossible without OS reinstall |
 | **Standalone single-file build** | Yes (WinSwift-Standalone.ps1 bundles all modules) | No | No | No | N/A |
 
 ## Why WinSwift Uses Non-Destructive GPO Suppression

docs/Execution-Architecture.md

@@ -11,7 +11,7 @@ Before any module executes, WinSwift validates the runtime environment:
 3. **Mark-of-the-Web handling** - Unblocks only marked PowerShell source files when Group Policy overrides the execution policy. Executable and data files are not unblocked.
 4. **Domain-join warning** - Detects domain-joined systems and warns that Group Policy may override applied registry changes after the next policy refresh.
 5. **Path and asset validation** - Confirms that all required directories (`Assets`, `Config`, `Regfiles`, `Schemas`, `Scripts`) are present before loading any module.
-6. **Registry backup** - Exports a timestamped `.reg` snapshot of all scheduled modification targets to `%TEMP%\WinSwift_Backup_<timestamp>` unless `-SkipRegistryBackup` is explicitly specified.
+6. **Registry backup** - Captures a timestamped JSON snapshot of all scheduled modification targets to `Backups\WinSwift-RegistryBackup-<timestamp>.json` unless `-SkipRegistryBackup` is explicitly specified. This snapshot is what automatic rollback restores from.
 7. **System restore point** - Creates a system restore point before executing any of the four high-impact custom modules: gaming optimization, extended AI purge, security hardening, or telemetry firewall.
 
 ## Feature Definition: Config/Features.json
@@ -82,20 +82,36 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\WinSwift.ps1 -Verify -
 
 ## Rollback Protocols
 
-### Registry Rollback
+### Automatic Rollback
 
-Apply the timestamped `.reg` export via:
+When the apply phase fails, WinSwift restores the backup taken before the run. The backup is captured in phase 1, before anything is written, so the material needed to recover already exists at the moment of failure.
+
+A registry import failure triggers the restore, whether it was counted through `$script:RegistryImportFailures` or thrown as an exception. An app removal failure does not: a registry backup cannot reinstall a removed Appx package, so restoring there would claim a recovery that did not happen. Undo work is skipped after a rollback.
+
+Exit code `3` means the run failed and was rolled back cleanly. Exit code `4` means the rollback itself failed, and the run summary names the backup file so recovery can be finished by hand.
+
+Pass `-NoAutoRollback` to leave the failed state in place.
+
+### Manual Registry Rollback
+
+Backups are JSON, not `.reg` exports, and are restored through the engine rather than `reg import`:
 
 ```powershell
-reg import "%TEMP%\WinSwift_Backup_<timestamp>.reg"
+. .\Scripts\Features\RestoreRegistryBackup.ps1
+$backup = Load-RegistryBackupFromFile -FilePath '.\Backups\WinSwift-RegistryBackup-<timestamp>.json'
+Restore-RegistryBackupState -Backup $backup
 ```
 
-Or through the built-in revert flow:
+### Feature Undo
+
+Revert individual features by id:
 
 ```powershell
-powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\WinSwift.ps1 -Revert
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\WinSwift.ps1 -CLI -Silent -Undo DisableTelemetry
 ```
 
+Undo covers the 87 of 112 features that declare a `RegistryUndoKey` or have a case in `Invoke-FeatureUndo`. The rest are rejected rather than silently doing nothing.
+
 ### System Restore Rollback
 
 For changes applied through the four high-impact custom modules, the System Restore point created before execution provides a full OS-level rollback path accessible through `rstrui.exe` or the Settings app.

docs/WIKI.md

@@ -21,7 +21,8 @@ The main script acts as the orchestrator. It manages:
    - *Appx Package Removal*
    - *UI/UX Modifications*
    - *AI/Copilot Purge*
-5. **Completion & Summary:** The script outputs a detailed summary of all modified keys, services, and packages.
+5. **Rollback on Failure:** If the apply phase fails, the registry backup taken before the run is restored automatically and undo work is skipped. Exit code `3` reports a clean rollback, `4` a rollback that itself failed.
+6. **Completion & Summary:** The script outputs a detailed summary of all modified keys, services, and packages, and writes it to `%TEMP%\WinSwift_RunSummary_<timestamp>.json`.
 
 ## ✨ Features
 
@@ -80,7 +81,7 @@ System Administrators can deploy WinSwift using management tools (e.g., Intune,
 
 WinSwift implements strict security guidelines to protect the host system:
 
-- **State Reversion:** Modifications are designed to be easily reversible. Users can undo changes via built-in revert scripts.
+- **State Reversion:** Modifications are reversible. Pass `-Undo <FeatureId>` to revert individual features from the command line, or use the GUI. A failed apply rolls itself back from the pre-run backup.
 - **Protocol Hardening:** Closes common attack vectors by disabling outdated protocols (SMBv1, TLS 1.0) and blocking AutoRun and Windows Script Host.
 - **Code Integrity:** All components are written in standard PowerShell. WinSwift strictly avoids downloading compiled binary executables (`.exe`) from untrusted third parties.
 - **Open Source Transparency:** The entire codebase is open-source, allowing for full security audits before deployment.