Pav-Osmolski · Oct 12, 2026 · Oct 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -2,135 +2,56 @@
 
 # DS4Windows 5
 
-### Feel more. Play your way.
+Controller remapping, advanced feedback, and per-game profiles for Windows.
 
-Game-authored DualSense haptics over Bluetooth. Switch 2 controllers on PC.
-Profiles that follow the game you're playing.
-
-**Free and open source.**
-
-[**Download**](https://github.com/hbashton/DS4Windows/releases) · [Getting started](docs/getting-started.md) · [Community](https://www.reddit.com/r/DS4Windows/)
+[**Download**](https://github.com/hbashton/DS4Windows/releases) · [Documentation](docs/README.md) · [Changelog](CHANGELOG.md) · [Community](https://www.reddit.com/r/DS4Windows/)
 
 [![Releases](https://img.shields.io/github/v/release/hbashton/DS4Windows?include_prereleases&logo=github&label=release)](https://github.com/hbashton/DS4Windows/releases)
 [![Main build](https://github.com/hbashton/DS4Windows/actions/workflows/ci-build.yml/badge.svg?branch=main)](https://github.com/hbashton/DS4Windows/actions/workflows/ci-build.yml?query=branch%3Amain)
+[![Required USB/IP: usbip-win2 0.9.7.7](https://img.shields.io/badge/USB%2FIP_required-0.9.7.7-blue)](https://github.com/vadimgrn/usbip-win2/releases/tag/v.0.9.7.7)
 
-<img src="docs/images/tour/overview.png" width="1000" alt="DS4Windows overview with a connected controller, profile selection, and quick controls">
-
-</div>
-
-DS4Windows brings controller remapping, native game feedback, and per-game
-settings together. Use the controller you enjoy, choose the controller your
-game expects, and make the controls your own.
-
-## Keep the detail. Lose the cable.
-
-Enjoy accurate, game-authored **DualSense advanced haptics and adaptive
-triggers** on DualSense and DualSense Edge—even over Bluetooth. Emulate a
-DualSense to receive native feedback from supported PC games, with advanced
-haptics kept distinct from ordinary rumble.
-
-Want to create your own trigger feel? **Trigger Lab** lets you design, preview,
-and save effects independently for each trigger, right in your profile.
-
-## Bring your Switch 2 controller to PC
-
-Use **Switch 2 Pro over USB or Bluetooth**, or **Joy-Con 2 over Bluetooth**,
-with remapping, gyro aiming, and HD rumble. Play with one Joy-Con, link a pair,
-or let automatic pairing bring them together. Original Switch Pro and Joy-Con
-controllers are supported too.
-
-**Try DualSense emulation with your Switch 2 Pro or Joy-Con 2:** compatible
-games' advanced haptics can be translated into HD rumble. Xbox rumble and
-impulse-trigger vibration can be translated too. The result is adapted to
-Nintendo's motors; it does not reproduce physical adaptive-trigger resistance.
-
-## A setup for every game
+![DS4Windows VIIPER](docs/images/promo/DS4Windows.webp)
 
-Gyro aiming for a shooter. Different stick curves for a racer. A comfortable
-layout for an RPG. Save your mappings, emulated controller, lighting, and
-feedback preferences in profiles, then use **Auto Profiles** to switch by
-game or application. You can match an executable or window title and assign
-profiles to individual controller slots.
+<img src="docs/images/tour/overview.png" width="1000" alt="DS4Windows overview with a connected controller and profile controls">
 
-Import, export, and share your profiles—or switch them yourself whenever
-you want.
-
-## More ways to make it yours
-
-- **Remap with a live preview.** Assign controller buttons, keyboard keys,
-  mouse clicks, macros, and special actions while checking your inputs.
-- **Aim your way.** Gyro mouse, flick stick, touchpad controls, and dual-Joy-Con
-  aiming. Joy-Con 2 also supports its optical mouse input.
-- **Feel your audio.** Turn game, app, or system audio into haptics on
-  DualSense and HD rumble on Switch 2 Pro / Joy-Con 2.
-- **Put controller audio to work.** Speaker, headset, and microphone routing
-  for supported PlayStation controllers, including Bluetooth audio.
-- **Keep everyday play convenient.** Searchable profiles, HidHide integration
-  to prevent double input, and Game Bar compatibility.
-
-Features depend on the physical controller and connection. Native advanced
-haptics and game-controlled adaptive triggers also require game support.
-
-## Your controller in. Your choice out.
-
-**Physical controllers:** DualShock 4, DualSense, DualSense Edge, DualShock 3,
-Switch Pro, Joy-Con, Switch 2 Pro, and Joy-Con 2. Compatible third-party devices
-and optional Moonlight/Sunshine input are also supported where their reports
-match a supported controller type.
-
-**Emulated controllers:** Xbox 360, Xbox One / Series, DualShock 4, DualSense,
-DualSense Edge, and Switch 2 Pro. Choose the output in your profile; available
-inputs and feedback still depend on the controller in your hands.
-
-## Get playing
-
-1. Download the newest **release candidate** from [Releases](https://github.com/hbashton/DS4Windows/releases).
-   Choose the **x64 Setup EXE** for the easiest installation.
-2. Follow setup. The matching VIIPER backend and USB/IP driver are bundled;
-   select **HidHide** to help prevent double input. Restart if prompted.
-3. Connect your controller and choose a profile. For Switch 2 Bluetooth,
-   use DS4Windows' discovery and association controls in **Settings**.
-4. Choose your emulated controller. For native DualSense feedback, select
-   **DualSense** and enable controller audio/speaker support. Turn off
-   overlapping Steam Input remapping for that game, then launch it.
-
-**Requirements:** Windows 10 or 11 **x64** and the
-[Visual C++ x64 runtime](https://aka.ms/vs/17/release/vc_redist.x64.exe).
-The .NET runtime is included. Current builds are release candidates; read the
-release notes for known limitations and signing status.
-
-Prefer portable? Download `DS4Windows_VIIPER_x64.zip` and extract the **entire**
-package. See [setup, updates, and troubleshooting](docs/getting-started.md) for
-driver requirements and keeping your profiles.
+</div>
 
-## Take a closer look
+DS4Windows builds on the work of its maintainers, earlier projects and the controller community.
 
-<details>
-<summary>Preview button mapping, Auto Profiles, and Trigger Lab</summary>
+## Features
 
-### Button mapping
+- Remap buttons, sticks, touchpad, keyboard, mouse, macros, and special actions.
+- Accept supported Moonlight/Sunshine virtual controllers, with an optional direct bridge for a matching Sunshine backend.
+- Save per-game profiles and switch them automatically by application or window title.
+- Configure gyro aiming, lighting, rumble, audio haptics, and adaptive triggers.
+- Receive native DualSense advanced haptics and adaptive-trigger feedback in supported games, including over Bluetooth.
 
-<img src="docs/images/tour/profile-editor.png" width="900" alt="Controller-aware profile editor and button mapping">
+Supported inputs include DualShock 3/4, DualSense/Edge, Switch Pro, Joy-Con,
+Switch 2 Pro, and Joy-Con 2. Outputs include Xbox 360, Xbox One/Series,
+DualShock 4, DualSense/Edge, and Switch 2 Pro. Features depend on the
+controller, connection, and game.
 
-### Auto Profiles
+## Get started
 
-<img src="docs/images/tour/auto-profiles.png" width="900" alt="Game and application rules for automatic profile selection">
+1. Download the **x64 Setup EXE** from [Releases](https://github.com/hbashton/DS4Windows/releases).
+2. Follow setup to install the bundled VIIPER backend and USB/IP driver. HidHide helps prevent double input; restart if prompted.
+3. Connect your controller and choose a profile and emulated controller. Avoid overlapping Steam Input remapping for the same game.
 
-### Trigger Lab
+**Requirements:** Windows 10 or 11 x64 and the [Visual C++ x64 runtime](https://aka.ms/vs/17/release/vc_redist.x64.exe). The .NET runtime is included.
 
-<img src="docs/images/tour/trigger-lab.png" width="900" alt="Trigger Lab with independent left and right adaptive-trigger controls">
+For portable use, extract the entire `DS4Windows_<version>_x64.zip`, keeping the
+`Lang` folder with the app. See [Documentation](docs/README.md) for
+setup, update instructions, and troubleshooting. Read the release notes for
+signing status and known limitations.
 
-</details>
+## Project links
 
-## Join in
+[Support development](https://www.paypal.com/paypalme/hbashton) · [Report a bug](https://github.com/hbashton/DS4Windows/issues) · [Contribute](contributing.md) · [VIIPER backend](https://github.com/hbashton/VIIPER) · [DS4Updater](https://github.com/hbashton/DS4Updater)
 
-[Report a bug](https://github.com/hbashton/DS4Windows/issues) ·
-[Share your setup](https://www.reddit.com/r/DS4Windows/) ·
-[Contribute](contributing.md) ·
-[Support development](https://www.paypal.com/paypalme/hbashton)
+Use the matching backend bundled with DS4Windows. The updater is optional
+when downloading and installing updates manually.
 
-This hbashton fork builds on the work of Jays2Kings, Ryochan7, Schmaldeo, and
-the DS4Windows community, with thanks to VIIPER, HidHide, usbip-win2, and the
-wider controller-research community.
+Thanks to hbashton, Jays2Kings, Ryochan7, Schmaldeo, the DS4Windows community,
+and the contributors to VIIPER, HidHide, usbip-win2, and controller research.
 
 Licensed under [GPL-3.0](COPYING). See [third-party notices](NOTICE.txt).
diff --git a/TODO.md b/TODO.md
diff --git a/contributing.md b/contributing.md
@@ -1,8 +1,36 @@
-## Pull Requests
-
-Pull requests for DS4Windows are welcome. Before making a pull request, please
-test your changes to ensure that the changes made do not negatively affect
-the performance of other parts of the application. Some consideration will
-be made during code review to try to tweak the changes in order to improve
-application performance. However, there is a chance that a pull request will be
-rejected if no reasonable solution can be found to incorporate code changes.
+# Contributing to DS4Windows
+
+Use [this project's issues](https://github.com/hbashton/DS4Windows/issues) and
+[pull requests](https://github.com/hbashton/DS4Windows/pulls).
+Credit upstream contributors when importing fixes; keep upstream issue links
+explicit so readers know which repository they belong to.
+
+## Report a bug
+
+Check [Troubleshooting](docs/troubleshooting.md) and search existing reports.
+Include app version, Windows build, controller model, USB/Bluetooth connection,
+virtual output, installation type, steps and relevant logs. Review logs for
+personal data. A reproducible small case is more useful than a long speculation.
+
+## Propose a change
+
+Start from the current default branch. Explain the concrete problem, resulting
+behaviour and validation. Keep unrelated changes separate. For controller and
+audio changes, describe ownership, ordering and performance implications where
+relevant. Tests must exercise behaviour rather than merely duplicate implementation.
+
+Use [Development](docs/development.md) for build/test commands and
+[Technical reference](docs/reference.md) for runtime contracts. State which
+hardware was tested and which checks remain unverified. Documentation-only
+changes need link and content checks; they do not require installing software.
+
+## Documentation and releases
+
+- Keep README short and point readers to the documentation index.
+- Put user instructions in the maintained guide rather than another root-level copy.
+- Keep release history in CHANGELOG.md; retain dated validation as evidence.
+- Mark design proposals and historical records clearly. Age alone does not make
+  an implementation contract obsolete.
+- Keep source, package and installer versions coordinated through the
+  [release workflow](.github/workflows/release.yml).
+- Preserve licensing notices and credits. Do not imply that an unsigned build is signed.
diff --git a/docs/CONTROLLER_PLATFORM_CHECKPOINT_2026_09_06.md b/docs/CONTROLLER_PLATFORM_CHECKPOINT_2026_09_06.md
@@ -1,5 +1,8 @@
 # Controller platform source checkpoint, 2026-09-06
 
+> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](README.md).
+
+
 This checkpoint preserves the accumulated Switch 2 Pro/Joy-Con USB/Bluetooth,
 canonical mapping, feedback/HD-rumble, profile/lifecycle and Xbox One VIIPER
 output work on `feature/native-udecx-landing-zone`. It is not a release tag or

diff --git a/docs/DSX-game-mod-support.md b/docs/DSX-game-mod-support.md
@@ -63,7 +63,7 @@ output semantics are verified. Calibration commands are never forwarded. Mods
 that require these unsupported modes or DSX-specific app discovery need further
 compatibility work; they should not be advertised as already supported.
 
-`test_dsx_mod.ps1` queries status by default. Its explicit `-TestEffects` switch
+[utils/test_dsx_mod.ps1](../test_dsx_mod.ps1) queries status by default. Its explicit `-TestEffects` switch
 briefly tests low-force right-trigger resistance and light output, then requests
 reset. Do not run effect tests while gaming. Unit tests use fake devices and
 ephemeral loopback ports, not physical controllers.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,43 @@
+# DS4Windows documentation
+
+For the current Windows x64 app. Start with the user guides; implementation
+contracts and dated validation records are intended for contributors.
+
+## Explore the app
+
+![DS4Windows overview](images/tour/overview.png)
+
+The [illustrated user guide](user-guide.md) walks through
+[controllers](user-guide.md#controllers), [profiles and remapping](user-guide.md#profiles),
+[Audio Haptics](user-guide.md#audio-haptics), [Trigger Lab](user-guide.md#trigger-lab),
+[Auto Profiles](user-guide.md#auto-profiles), [Output Slots](user-guide.md#output-slots)
+and [Settings](user-guide.md#settings). Screenshots sit beside the controls they explain.
+
+## Use DS4Windows
+
+| Guide | What it covers |
+| --- | --- |
+| [Getting started](getting-started.md) | Requirements, installation, portable setup, updates and profiles |
+| [User guide](user-guide.md) | Controllers, profile editing, auto profiles, output slots, settings and logs |
+| [Troubleshooting](troubleshooting.md) | Detection, double input, backend startup, feedback and updates |
+| [Swipe profiles](swipe-profiles.md) | Restrict two-finger profile switching |
+| [Moonlight / Sunshine](moonlight-support.md) | Accept supported streamed virtual controllers |
+| [Flick stick](flick-stick-calibration.md) | Calibration and troubleshooting |
+| [Mouse clicks](troubleshooting-mouse-clicks.md) | Diagnosing simultaneous mouse-button mappings |
+| [DSX game mods](DSX-game-mod-support.md) | Optional mod integration and its limits |
+| [DualSense Bluetooth audio](dualsense-bluetooth-audio-haptics.md) | Audio and haptics transport details |
+
+## Contribute and maintain
+
+- [Contributing](../contributing.md): reporting bugs, proposing changes and documentation rules.
+- [Development](development.md): build, tests, packaging and code layout.
+- [Roadmap](roadmap.md): priorities and proposals, rather than a completed-task list.
+- [Release workflow](../.github/workflows/release.yml): upstream build, signing and publication requirements.
+- [Installer](../installer/README.md) and [installer validation](INSTALLER_VALIDATION_STRATEGY.md).
+- [Translations](dev/translations.md) and [profile schema reference](dev/profile-schema-reference.md).
+- [Technical reference](reference.md): runtime contracts and diagnostic tools.
+- [Validation archive](validation/README.md): dated tests and investigations.
+
+Release history belongs in [CHANGELOG.md](../CHANGELOG.md). Keep one canonical
+page per topic, and link directly to it. A dated investigation describes its
+recorded source and hardware; it does not establish the status of a newer build.