feat: initial commit — README, community files, docs, templates, branding

2026-07-29 11:24:06 -07:00 · 2026-07-12 18:33:25 -07:00
commit 3db1201879
27 changed files with 3695 additions and 0 deletions
@@ -0,0 +1,22 @@
+# Default owners for everything in the repo
+# Each line is a file pattern followed by one or more owners
+
+# Global owners
+* @gshellmr-code
+
+# Build pipeline
+build/ @gshellmr-code
+*.nsi @gshellmr-code
+*.spec @gshellmr-code
+build.bat @gshellmr-code
+build2.bat @gshellmr-code
+
+# Native modules
+native/ @gshellmr-code
+
+# Documentation
+docs/ @gshellmr-code
+*.md @gshellmr-code
+
+# CI/CD
+.github/ @gshellmr-code
@@ -0,0 +1,10 @@
+# These are supported funding model platforms
+
+github: [gshellmr-code]
+# ko_fi: # Replace with a single Ko-fi username
+# open_collective: # Replace with a single Open Collective username
+# patreon: # Replace with a single Patreon username
+# community_bridge: # Replace with a single Community Bridge project name
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
+custom:
+  - https://buymeacoffee.com/mrcyberdev
@@ -0,0 +1,140 @@
+name: Bug Report
+description: Report a bug in WSA Installer
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug! Please fill out the form below to help us identify and fix the issue.
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of WSA Installer is affected?
+      options:
+        - Installation (WSA setup)
+        - Play Store integration
+        - Background Service
+        - File Sharing (WebDAV)
+        - Repair flow
+        - Uninstall flow
+        - Self-Update
+        - UI / GUI
+        - System Detection
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: WSA Installer Version
+      description: "Find this in the About section or title bar"
+      placeholder: "e.g., 1.2.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Windows Version
+      description: "e.g., Windows 11 23H2, Windows 10 22H2"
+      placeholder: "e.g., Windows 11 23H2"
+    validations:
+      required: true
+
+  - type: input
+    id: hardware
+    attributes:
+      label: Hardware Info (optional)
+      description: "CPU, RAM, and any relevant hardware details"
+      placeholder: "e.g., Intel i7-12700K, 16GB RAM"
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of the bug.
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Open WSA Installer
+        2. Click on '...'
+        3. Scroll down to '...'
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+      placeholder: Describe what you expected...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened.
+      placeholder: Describe what actually happened...
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs
+      description: "Paste any relevant log output. Check `wsa_activity.log` for session logs."
+      render: shell
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots (optional)
+      description: If applicable, add screenshots to help explain the problem.
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation Method
+      options:
+        - NSIS Installer (WSA_Installer_Setup.exe)
+        - Build from source (run.bat)
+        - Portable (direct run)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: playstore
+    attributes:
+      label: Play Store Installed?
+      options:
+        - "Yes"
+        - "No"
+        - Attempted but failed
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues to avoid duplicates
+          required: true
+        - label: I have checked the troubleshooting guide
+          required: false
+        - label: I have attached relevant log files
+          required: false
@@ -0,0 +1,79 @@
+name: Feature Request
+description: Suggest a new feature for WSA Installer
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a feature! Please fill out the form below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: "What problem does this feature solve? Is it related to a frustration?"
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like.
+      placeholder: "I'd like WSA Installer to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Describe any alternative solutions or features you've considered.
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of WSA Installer does this affect?
+      options:
+        - Installation flow
+        - WSA management
+        - Play Store integration
+        - File sharing (WebDAV)
+        - Background service
+        - UI / GUI
+        - Build system
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: How important is this feature to you?
+      options:
+        - Nice to have
+        - Important
+        - Critical (blocking my workflow)
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or examples about the feature request.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing feature requests to avoid duplicates
+          required: true
+        - label: I would be willing to help implement this feature
+          required: false
@@ -0,0 +1,80 @@
+name: Support Request
+description: Get help with WSA Installer
+title: "[Help]: "
+labels: ["question", "help wanted"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Need help with WSA Installer? Please provide as much detail as possible.
+
+  - type: dropdown
+    id: topic
+    attributes:
+      label: Help Topic
+      options:
+        - Installation issues
+        - Play Store issues
+        - WSA won't start
+        - Background service issues
+        - File sharing (WebDAV)
+        - Repair / Uninstall
+        - Update issues
+        - General usage
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: WSA Installer Version
+      placeholder: "e.g., 1.2.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Windows Version
+      placeholder: "e.g., Windows 11 23H2"
+    validations:
+      required: true
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Your Question
+      description: Describe what you need help with.
+      placeholder: "I'm trying to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-tried
+    attributes:
+      label: What Have You Tried?
+      description: Describe what you've already attempted.
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs (optional)
+      description: "Paste any relevant log output from `wsa_activity.log` or the UI."
+      render: shell
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots (optional)
+      description: Add screenshots if applicable.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I have checked the troubleshooting guide
+          required: true
+        - label: I have searched existing issues for similar questions
+          required: true
@@ -0,0 +1,64 @@
+---
+name: Pull Request
+about: Submit changes to WSA Installer
+title: ''
+labels: ''
+assignees: ''
+---
+
+## Description
+
+<!-- Briefly describe what this PR does and why. -->
+
+## Type of Change
+
+<!-- Check the relevant option(s): -->
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactoring (code changes that neither fix a bug nor add a feature)
+- [ ] Performance improvement
+- [ ] Build / CI change
+
+## Related Issues
+
+<!-- Link any related issues: -->
+
+Closes #(issue number)
+
+## Changes Made
+
+<!-- List the specific changes made in this PR: -->
+
+- Change 1
+- Change 2
+- Change 3
+
+## Testing
+
+<!-- Describe how you tested these changes: -->
+
+- [ ] Tested on Windows 10
+- [ ] Tested on Windows 11
+- [ ] Tested with Play Store installation
+- [ ] Tested repair flow
+- [ ] Tested uninstall flow
+- [ ] Tested background service
+- [ ] Tested file sharing (WebDAV)
+- [ ] Tested self-update
+
+## Screenshots
+
+<!-- If applicable, add screenshots to help explain your changes. -->
+
+## Checklist
+
+- [ ] My code follows the project's code style
+- [ ] I have self-reviewed my code
+- [ ] I have added comments for complex logic
+- [ ] I have updated documentation as needed
+- [ ] I have added tests that prove my fix is effective or my feature works
+- [ ] New and existing tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to WSA Installer will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-07-12
+
+### Added
+- File sharing via WebDAV (user and root modes)
+- Drive mounting as Windows network drives
+- Advanced settings page with file sharing controls
+- Auto-repair toggle in advanced settings
+- Background service GUI monitor dialog
+- 30-chunk parallel download for self-updates
+- Download resume support across sessions
+- Drive letter selection for WebDAV mounts
+- Custom drive labels and icons via registry
+
+### Changed
+- Upgraded to Python 3.14
+- Improved download speed with parallel chunks
+- Enhanced error handling with retry logic
+- Updated NSIS installer with maintenance mode
+- Improved glass transparency system
+
+### Fixed
+- WsaClient.exe crash on Windows 10 (WSAPatch)
+- ADB authorization popup automation reliability
+- Service auto-restart on failure
+- Single-instance lock release on uninstall
+
+## [1.1.0] - 2026-06-01
+
+### Added
+- Background service (`WSABackgroundService`)
+- Windows Service integration with auto-restart
+- Remote configuration via Rust security gateway
+- Self-update mechanism
+- Repair flow from Windows Settings
+- YouTube channel subscription on completion
+
+### Changed
+- Improved system detection (5 methods)
+- Enhanced Play Store patching with 7-phase flow
+- Better progress tracking with phase headers
+
+### Fixed
+- Virtualization detection on certain hardware
+- Hyper-V enabling on Windows 10
+
+## [1.0.0] - 2026-05-01
+
+### Added
+- Initial release
+- 5-step installation wizard
+- System detection (virtualization, Hyper-V, VMP, WSL)
+- WSA download with parallel chunks
+- 7z extraction with nested folder detection
+- 6-phase WSA installation
+- 7-phase Play Store integration
+- ADB authorization automation
+- Glass transparency UI
+- NSIS professional installer
+- Silent installation support
+- Single-instance enforcement
@@ -0,0 +1,129 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at the
+[GitHub Issues](https://github.com/WSA-Installer/wsa-installer/issues).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
@@ -0,0 +1,209 @@
+# Contributing to WSA Installer
+
+Thank you for your interest in contributing to WSA Installer! This document provides guidelines and information for contributors.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for everyone. Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating a bug report, please check [existing issues](https://github.com/WSA-Installer/wsa-installer/issues) to avoid duplicates.
+
+When creating a bug report, include:
+
+- **Clear title** — Describe the issue concisely
+- **WSA Installer version** — Found in the About section
+- **Windows version** — e.g., Windows 11 23H2
+- **Steps to reproduce** — Detailed steps to trigger the bug
+- **Expected behavior** — What you expected to happen
+- **Actual behavior** — What actually happened
+- **Logs** — Relevant log output from `wsa_activity.log` or the UI log
+
+### Suggesting Features
+
+Feature suggestions are welcome! Please provide:
+
+- **Problem statement** — What problem does this solve?
+- **Proposed solution** — How should it work?
+- **Alternatives considered** — Other approaches you thought about
+- **Component** — Which part of the installer does this affect?
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Test thoroughly on Windows 10 and/or Windows 11
+5. Commit with a descriptive message
+6. Push to your fork
+7. Open a Pull Request
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.14
+- Windows 10/11
+- Administrator privileges (for testing)
+- Git
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/WSA-Installer/wsa-installer.git
+cd wsa-installer
+
+# Run the development launcher
+run.bat
+```
+
+The `run.bat` script will:
+1. Create a Python virtual environment if it doesn't exist
+2. Install all dependencies from `requirements.txt`
+3. Launch the application
+
+### Project Structure
+
+```
+wsa-installer/
+├── src/
+│   ├── app.py                    # Main application (~11K lines)
+│   ├── run.py                    # Entry point
+│   ├── WSARepair.py              # Windows Settings proxy
+│   └── patch_flet.py             # Flet client patcher
+├── assets/                       # Runtime resources
+├── native/                       # Rust native modules
+├── emb_py/                       # Embedded Python 3.14
+├── build/                        # Build scripts
+├── docs/                         # Documentation
+└── tests/                        # Tests
+```
+
+### Key Files
+
+- **`app.py`** — The main application file containing the Flet GUI, installer logic, background service, repair, update, and file sharing functionality
+- **`WSARepair.py`** — Proxy for Windows Settings Repair/Uninstall buttons
+- **`build.bat`** — Primary build pipeline (Nuitka → PyInstaller → NSIS)
+
+## Code Style
+
+### Python
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) style guide
+- Use meaningful variable and function names
+- Add docstrings for public functions and classes
+- Keep functions focused and concise
+- Use type hints where appropriate
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>(<scope>): <description>
+
+Types:
+  feat     - New feature
+  fix      - Bug fix
+  docs     - Documentation changes
+  style    - Code style changes (formatting, etc.)
+  refactor - Code refactoring
+  perf     - Performance improvements
+  test     - Adding or updating tests
+  build    - Build system changes
+  ci       - CI/CD changes
+  chore    - Maintenance tasks
+
+Scopes:
+  installer  - Main installer
+  service    - Background service
+  webdav     - File sharing
+  ui         - User interface
+  build      - Build pipeline
+  docs       - Documentation
+```
+
+Examples:
+```
+feat(installer): add parallel chunked download with resume
+fix(service): resolve WSA port detection timeout
+docs(readme): update installation guide
+build(nsis): add silent install support
+```
+
+### Branch Naming
+
+- `feature/description` — New features
+- `fix/description` — Bug fixes
+- `docs/description` — Documentation changes
+- `release/version` — Release preparation
+
+## Testing
+
+### Manual Testing
+
+Before submitting a PR, test the following flows:
+
+1. **Fresh Install** — Install WSA on a clean system
+2. **Play Store** — Verify Play Store integration works
+3. **Repair** — Test the repair flow from Windows Settings
+4. **Uninstall** — Verify complete uninstallation
+5. **Update** — Test the self-update mechanism
+6. **File Sharing** — Test WebDAV drive mounting
+
+### Test Checklist
+
+- [ ] Tested on Windows 10 (build 19041+)
+- [ ] Tested on Windows 11
+- [ ] Tested with Play Store installation
+- [ ] Tested repair flow
+- [ ] Tested uninstall flow
+- [ ] No new warnings or errors
+- [ ] UI renders correctly at different DPI settings
+
+## Building
+
+### Development Build
+
+```cmd
+run.bat
+```
+
+### Release Build
+
+```cmd
+build.bat
+```
+
+This will produce `dist/WSA_Installer_Setup.exe`.
+
+### Build Requirements
+
+- Python 3.14 with pip
+- Nuitka (`pip install nuitka`)
+- PyInstaller (`pip install pyinstaller`)
+- NSIS ([nsis.sourceforge.io](https://nsis.sourceforge.io))
+
+## Documentation
+
+- Update `docs/` if adding new features
+- Update `README.md` if changing public API or behavior
+- Add entries to `CHANGELOG.md` for notable changes
+- Update `ROADMAP.md` if adding planned features
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+
+## Questions?
+
+If you have questions about contributing, feel free to:
+
+- Open a [Discussion](https://github.com/WSA-Installer/wsa-installer/discussions)
+- Contact via [YouTube](https://www.youtube.com/@AT_Tech_Zone)
+
+Thank you for contributing to WSA Installer!
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AT Tech Zone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,101 @@
+# Roadmap
+
+This document outlines the planned features and improvements for WSA Installer.
+
+## Current Release: v1.2.x
+
+**Status:** Active development and maintenance
+
+### Completed
+
+- [x] One-click WSA installation
+- [x] Play Store integration (MindTheGapps 13.0)
+- [x] Background service (`WSABackgroundService`)
+- [x] Self-update system with parallel downloads
+- [x] Repair and uninstall flows
+- [x] File sharing via WebDAV
+- [x] Glass transparency UI
+- [x] Remote configuration via Rust gateway
+- [x] NSIS professional installer
+- [x] ADB authorization automation
+- [x] WSAPatch for Windows 10 compatibility
+- [x] Single-instance enforcement
+- [x] Activity logging
+
+## Planned: v1.3.0
+
+**Target:** Q3 2026
+
+### Features
+
+- [ ] WSA version manager (install/switch between versions)
+- [ ] Custom GApps selection (NikGapps, FlameGapps, MindTheGapps)
+- [ ] WSA settings backup and restore
+- [ ] ADB shell integration in UI
+- [ ] Performance monitoring dashboard
+- [ ] Automatic Hyper-V configuration wizard
+
+### Improvements
+
+- [ ] Improved download speeds with additional CDN sources
+- [ ] Better error messages and recovery suggestions
+- [ ] Enhanced glass transparency with blur effects
+- [ ] Progress notification in Windows Action Center
+
+## Planned: v1.4.0
+
+**Target:** Q4 2026
+
+### Features
+
+- [ ] WSA app data export/import
+- [ ] Multi-language support (i18n)
+- [ ] Dark/light theme toggle
+- [ ] Command-line batch operations
+- [ ] WSA snapshot and restore
+- [ ] Custom ADB port configuration
+
+### Infrastructure
+
+- [ ] MSI installer alternative
+- [ ] Winget package
+- [ ] Chocolatey package
+- [ ] Scoop package
+- [ ] Automated CI/CD pipeline
+
+## Planned: v2.0.0
+
+**Target:** 2027
+
+### Major Features
+
+- [ ] Complete UI redesign with Fluent Design
+- [ ] Plugin system for custom integrations
+- [ ] WSA marketplace integration
+- [ ] Cross-platform support (Linux, macOS)
+- [ ] WSA container management
+- [ ] Enterprise deployment tools
+
+## Long-Term Vision
+
+- Become the definitive tool for WSA management
+- Support all future WSA versions and Windows updates
+- Build a community-driven plugin ecosystem
+- Provide enterprise-grade deployment and management tools
+- Maintain compatibility with new Android versions
+
+## How to Contribute
+
+We welcome contributions to help实现 these features! See our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Priority Areas
+
+1. **Testing** — Help us test on different hardware configurations
+2. **Documentation** — Improve guides and troubleshooting
+3. **Localization** — Translate to other languages
+4. **Bug Reports** — Report and help fix issues
+5. **Feature Development** — Implement planned features
+
+## Feedback
+
+Have ideas for the roadmap? Open a [Discussion](https://github.com/WSA-Installer/wsa-installer/discussions) or vote on existing [Feature Requests](https://github.com/WSA-Installer/wsa-installer/issues?q=label%3Aenhancement).
@@ -0,0 +1,87 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability within WSA Installer, please send an email to the project maintainers. All security vulnerabilities will be promptly addressed.
+
+**Please do NOT report security vulnerabilities through public GitHub issues.**
+
+### What to Include
+
+When reporting a vulnerability, please include:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+### Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial assessment**: Within 1 week
+- **Fix and release**: Depends on severity, typically within 2 weeks
+
+## Security Architecture
+
+WSA Installer implements multiple security layers:
+
+### Layer 1: Rust Security Gateway (`widget_ui.pyd`)
+
+- Zero-trust configuration parsing
+- Signature verification for remote config
+- Encrypted configuration handling
+- Hash-based deduplication to prevent redundant updates
+
+### Layer 2: Instance Enforcement
+
+- Socket-based single instance lock prevents multiple installer copies
+- Port-based process detection for conflict resolution
+
+### Layer 3: Windows Service
+
+- `WSABackgroundService` runs as SYSTEM-level Windows Service
+- Auto-restart on failure with configurable retry logic
+- User session process spawning via `CreateProcessAsUserW`
+
+### Layer 4: Source Protection
+
+- Nuitka compilation (`app.py` → `app.pyd`) for source code protection
+- PyInstaller bundling with binary obfuscation
+- Embedded Python 3.14 runtime isolation
+
+### Layer 5: Privilege Management
+
+- UAC elevation for system modifications
+- Administrator privilege validation before operations
+- Input blocking during sensitive automation sequences
+
+## Best Practices for Users
+
+1. **Download only from official sources** — Use the official GitHub releases
+2. **Run as administrator** — Required for WSA installation and system modifications
+3. **Keep updated** — Use the built-in self-update feature
+4. **Verify checksums** — Compare downloaded file hashes when possible
+5. **Review logs** — Check `wsa_activity.log` for suspicious activity
+
+## Security Updates
+
+Security updates will be released as patches to the current version. Users are encouraged to enable automatic updates or check the [Releases](https://github.com/WSA-Installer/wsa-installer/releases) page regularly.
+
+## Scope
+
+This security policy applies to:
+
+- The WSA Installer application (`WSA Installer.exe`)
+- The NSIS installer (`WSA_Installer_Setup.exe`)
+- The background service (`WSABackgroundService`)
+- The native modules (`widget_ui.pyd`, `playstore_patcher_mem.pyd`)
+
+It does NOT apply to:
+
+- Third-party software (ADB, Python, etc.)
+- Windows Subsystem for Android itself
+- Applications installed within WSA
+
+## Acknowledgments
+
+We appreciate the security research community and responsible disclosure of vulnerabilities.
@@ -0,0 +1,85 @@
+# Support
+
+## Getting Help
+
+If you need help with WSA Installer, here are the available support channels:
+
+### Documentation
+
+- [Installation Guide](docs/installation.md) — Step-by-step installation instructions
+- [Troubleshooting Guide](docs/troubleshooting.md) — Solutions to common issues
+- [CLI Reference](docs/cli-reference.md) — Command-line options
+- [Architecture Guide](docs/architecture.md) — Technical overview
+
+### Community Support
+
+| Channel | Link | Best For |
+|:--------|:-----|:---------|
+| GitHub Issues | [Report a Bug](https://github.com/WSA-Installer/wsa-installer/issues/new?template=bug_report.yml) | Bug reports and issues |
+| GitHub Discussions | [Ask a Question](https://github.com/WSA-Installer/wsa-installer/discussions) | Questions and general help |
+| YouTube | [@AT_Tech_Zone](https://www.youtube.com/@AT_Tech_Zone) | Video tutorials and guides |
+
+### Contact
+
+- **YouTube**: [@AT_Tech_Zone](https://www.youtube.com/@AT_Tech_Zone)
+- **Buy Me a Coffee**: [mrcyberdev](https://buymeacoffee.com/mrcyberdev)
+
+## Frequently Asked Questions
+
+### General
+
+**Q: What is WSA Installer?**
+A: WSA Installer is a tool that automates the installation of Windows Subsystem for Android (WSA) with Google Play Store on Windows 10 and Windows 11.
+
+**Q: Is WSA Installer free?**
+A: Yes, WSA Installer is free and open-source under the MIT License.
+
+**Q: Does WSA Installer work on Windows 10?**
+A: Yes, WSA Installer supports Windows 10 build 19041 and later.
+
+### Installation
+
+**Q: Do I need to be an administrator?**
+A: Yes, WSA Installer requires administrator privileges to install WSA and configure Windows features.
+
+**Q: Can I install WSA without Play Store?**
+A: Yes, the installer offers both options: WSA only or WSA with Play Store.
+
+**Q: How long does installation take?**
+A: Installation typically takes 5-15 minutes depending on your internet speed and system performance.
+
+**Q: What is bundle.wsa?**
+A: `bundle.wsa` is a pre-packaged archive containing WSA packages. It's optional — the installer can download packages directly from GitHub.
+
+### Troubleshooting
+
+**Q: Virtualization is not detected**
+A: Enable Intel VT-x or AMD-V in your BIOS/UEFI settings. Check your motherboard documentation for instructions.
+
+**Q: WSA won't start after installation**
+A: Try restarting your computer. If the issue persists, use the Repair feature from Windows Settings → Apps → WSA Installer → Modify → Repair.
+
+**Q: Play Store is not working**
+A: Ensure Developer Mode is enabled in WSA Settings. Try disconnecting and reconnecting ADB. Check the installer logs for errors.
+
+**Q: How do I uninstall WSA?**
+A: Use the WSA Installer's built-in uninstaller, or go to Windows Settings → Apps → WSA Installer → Uninstall.
+
+### Advanced
+
+**Q: Can I install multiple WSA versions?**
+A: Not currently. This is a planned feature for a future release.
+
+**Q: How do I use the background service?**
+A: The background service is installed automatically. It monitors WSA status and manages the Play Store SDK. You can manage it via Windows Services (`WSABackgroundService`).
+
+**Q: Can I use WSA Installer in enterprise environments?**
+A: Yes, WSA Installer supports silent installation via `/S` flag, making it suitable for enterprise deployment.
+
+## Feature Requests
+
+Have an idea for a new feature? [Open a feature request](https://github.com/WSA-Installer/wsa-installer/issues/new?template=feature_request.yml) on GitHub.
+
+## Contributing
+
+Want to help improve WSA Installer? See our [Contributing Guide](CONTRIBUTING.md) for details.
@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1B72C0;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#155A9A;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="12" ry="12" fill="url(#bg)"/>
+  <rect x="14" y="20" width="36" height="28" rx="4" ry="4" fill="none" stroke="white" stroke-width="2.5" opacity="0.95"/>
+  <line x1="14" y1="28" x2="50" y2="28" stroke="white" stroke-width="2.5" opacity="0.95"/>
+  <rect x="24" y="16" width="16" height="6" rx="2" ry="2" fill="none" stroke="white" stroke-width="2" opacity="0.95"/>
+  <circle cx="32" cy="37" r="6" fill="#3DDC84" opacity="0.9"/>
+  <circle cx="30" cy="36" r="1" fill="#1B72C0"/>
+  <circle cx="34" cy="36" r="1" fill="#1B72C0"/>
+  <text x="32" y="54" font-family="Segoe UI, Arial, sans-serif" font-size="7" font-weight="700" fill="white" text-anchor="middle" opacity="0.9">WSA</text>
+</svg>
@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="bgGradDark" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1E1E2E;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#151525;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="accentGradD" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#3DDC84;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#2BB568;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  <rect x="16" y="16" width="480" height="480" rx="64" ry="64" fill="url(#bgGradDark)"/>
+  <rect x="108" y="160" width="296" height="240" rx="24" ry="24" fill="none" stroke="#4A9AE8" stroke-width="16" opacity="0.95"/>
+  <line x1="108" y1="220" x2="404" y2="220" stroke="#4A9AE8" stroke-width="16" opacity="0.95"/>
+  <rect x="196" y="140" width="120" height="40" rx="12" ry="12" fill="none" stroke="#4A9AE8" stroke-width="14" opacity="0.95"/>
+  <circle cx="256" cy="300" r="44" fill="url(#accentGradD)" opacity="0.9"/>
+  <line x1="236" y1="258" x2="224" y2="238" stroke="#3DDC84" stroke-width="8" stroke-linecap="round" opacity="0.9"/>
+  <line x1="276" y1="258" x2="288" y2="238" stroke="#3DDC84" stroke-width="8" stroke-linecap="round" opacity="0.9"/>
+  <circle cx="240" cy="294" r="6" fill="#1E1E2E"/>
+  <circle cx="272" cy="294" r="6" fill="#1E1E2E"/>
+  <path d="M256 360 L256 390 M244 378 L256 390 L268 378" stroke="#4A9AE8" stroke-width="8" stroke-linecap="round" stroke-linejoin="round" fill="none" opacity="0.8"/>
+  <text x="256" y="440" font-family="Segoe UI, Arial, sans-serif" font-size="48" font-weight="700" fill="#4A9AE8" text-anchor="middle" opacity="0.95">WSA</text>
+</svg>
@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="bgGradLight" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#F0F4FF;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#E0E8F8;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="accentGradL" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#3DDC84;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#2BB568;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  <rect x="16" y="16" width="480" height="480" rx="64" ry="64" fill="url(#bgGradLight)"/>
+  <rect x="108" y="160" width="296" height="240" rx="24" ry="24" fill="none" stroke="#1B72C0" stroke-width="16" opacity="0.95"/>
+  <line x1="108" y1="220" x2="404" y2="220" stroke="#1B72C0" stroke-width="16" opacity="0.95"/>
+  <rect x="196" y="140" width="120" height="40" rx="12" ry="12" fill="none" stroke="#1B72C0" stroke-width="14" opacity="0.95"/>
+  <circle cx="256" cy="300" r="44" fill="url(#accentGradL)" opacity="0.9"/>
+  <line x1="236" y1="258" x2="224" y2="238" stroke="#3DDC84" stroke-width="8" stroke-linecap="round" opacity="0.9"/>
+  <line x1="276" y1="258" x2="288" y2="238" stroke="#3DDC84" stroke-width="8" stroke-linecap="round" opacity="0.9"/>
+  <circle cx="240" cy="294" r="6" fill="#F0F4FF"/>
+  <circle cx="272" cy="294" r="6" fill="#F0F4FF"/>
+  <path d="M256 360 L256 390 M244 378 L256 390 L268 378" stroke="#1B72C0" stroke-width="8" stroke-linecap="round" stroke-linejoin="round" fill="none" opacity="0.8"/>
+  <text x="256" y="440" font-family="Segoe UI, Arial, sans-serif" font-size="48" font-weight="700" fill="#1B72C0" text-anchor="middle" opacity="0.95">WSA</text>
+</svg>
@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1B72C0;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#155A9A;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#3DDC84;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#2BB568;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  <!-- Background rounded rectangle (Windows 11 style) -->
+  <rect x="16" y="16" width="480" height="480" rx="64" ry="64" fill="url(#bgGrad)"/>
+  <!-- Package/box shape -->
+  <rect x="108" y="160" width="296" height="240" rx="24" ry="24" fill="none" stroke="white" stroke-width="16" opacity="0.95"/>
+  <!-- Box lid line -->
+  <line x1="108" y1="220" x2="404" y2="220" stroke="white" stroke-width="16" opacity="0.95"/>
+  <!-- Box handle -->
+  <rect x="196" y="140" width="120" height="40" rx="12" ry="12" fill="none" stroke="white" stroke-width="14" opacity="0.95"/>
+  <!-- Android head silhouette (subtle, inside box) -->
+  <circle cx="256" cy="300" r="44" fill="url(#accentGrad)" opacity="0.9"/>
+  <!-- Android antennas -->
+  <line x1="236" y1="258" x2="224" y2="238" stroke="#3DDC84" stroke-width="8" stroke-linecap="round" opacity="0.9"/>
+  <line x1="276" y1="258" x2="288" y2="238" stroke="#3DDC84" stroke-width="8" stroke-linecap="round" opacity="0.9"/>
+  <!-- Android eyes -->
+  <circle cx="240" cy="294" r="6" fill="white"/>
+  <circle cx="272" cy="294" r="6" fill="white"/>
+  <!-- Down arrow (install indicator) -->
+  <path d="M256 360 L256 390 M244 378 L256 390 L268 378" stroke="white" stroke-width="8" stroke-linecap="round" stroke-linejoin="round" fill="none" opacity="0.8"/>
+  <!-- WSA text -->
+  <text x="256" y="440" font-family="Segoe UI, Arial, sans-serif" font-size="48" font-weight="700" fill="white" text-anchor="middle" opacity="0.95">WSA</text>
+</svg>
@@ -0,0 +1,165 @@
+# ADB Reference
+
+ADB (Android Debug Bridge) is used by WSA Installer to communicate with WSA for Play Store installation and management.
+
+## ADB in WSA Installer
+
+WSA Installer automates ADB operations for:
+
+- Connecting to WSA
+- Authorizing USB debugging
+- Installing Play Store (GApps)
+- Verifying package installation
+- Managing WSA developer options
+
+## ADB Connection
+
+### Port
+
+WSA exposes ADB on port **58526** by default.
+
+### Connect Command
+
+```cmd
+adb connect 127.0.0.1:58526
+```
+
+### Connection Process
+
+WSA Installer automatically:
+
+1. Checks if WSA is running
+2. Probes port 58526
+3. Connects via ADB
+4. Handles authorization (if needed)
+
+## ADB Authorization
+
+When connecting to WSA for the first time, you'll see an "Allow USB debugging" popup.
+
+### Automatic Authorization
+
+WSA Installer automates this process using `pywinauto`:
+
+1. Detects the "Allow USB debugging" window
+2. Clicks "Always allow from this computer"
+3. Clicks "Allow"
+
+### Manual Authorization
+
+If automatic authorization fails:
+
+1. Check the WSA window for the popup
+2. Check "Always allow from this computer"
+3. Click "Allow"
+
+## Common ADB Commands
+
+### Check Connected Devices
+
+```cmd
+adb devices
+```
+
+### Install APK
+
+```cmd
+adb install -r package.apk
+```
+
+### Uninstall Package
+
+```cmd
+adb uninstall com.package.name
+```
+
+### List Installed Packages
+
+```cmd
+adb shell pm list packages
+```
+
+### Check Specific Package
+
+```cmd
+adb shell pm list packages com.android.vending
+```
+
+### Start Activity
+
+```cmd
+adb shell am start -n com.package/.Activity
+```
+
+### Send Broadcast
+
+```cmd
+adb shell am broadcast -a com.action.NAME
+```
+
+## Troubleshooting ADB
+
+### "Device unauthorized"
+
+1. Check the WSA window for the authorization popup
+2. Enable Developer Mode in WSA Settings
+3. Disconnect and reconnect ADB:
+   ```cmd
+   adb disconnect
+   adb connect 127.0.0.1:58526
+   ```
+
+### "Connection refused"
+
+1. Ensure WSA is running
+2. Check that Developer Mode is enabled
+3. Restart WSA:
+   ```cmd
+   taskkill /F /IM WsaClient.exe
+   wsa://system
+   ```
+4. Wait 30 seconds, then retry
+
+### "Device offline"
+
+1. Disconnect ADB: `adb disconnect`
+2. Kill ADB server: `adb kill-server`
+3. Restart ADB server: `adb start-server`
+4. Reconnect: `adb connect 127.0.0.1:58526`
+
+### Port Changed
+
+If WSA uses a different port:
+
+1. Check WSA Settings → Developer → Wireless debugging
+2. Note the port number
+3. Connect with the correct port:
+   ```cmd
+   adb connect 127.0.0.1:PORT_NUMBER
+   ```
+
+### Multiple ADB Instances
+
+If you have multiple ADB installations:
+
+1. Use the full path to the WSA Installer's ADB:
+   ```
+   assets\adb.exe connect 127.0.0.1:58526
+   ```
+
+## ADB in WSA WebDev
+
+The WSA WebDev project uses ADB for server control:
+
+```bash
+# Start WebDAV server
+adb shell am broadcast -a com.wsa.webdav.START
+
+# Stop WebDAV server
+adb shell am broadcast -a com.wsa.webdav.STOP
+
+# Check status
+adb shell am broadcast -a com.wsa.webdav.STATUS
+```
+
+See the [WebDAV documentation](webdav.md) for details.
@@ -0,0 +1,301 @@
+# Architecture Guide
+
+This document describes the technical architecture of WSA Installer.
+
+## System Overview
+
+WSA Installer is a Python-based application with Rust native modules, designed to automate WSA installation and management on Windows.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     WSA Installer v1.2.0                      │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────┐    ┌──────────────────┐    ┌────────────┐  │
+│  │  Flet GUI   │    │  InstallerLogic   │    │  Remote    │  │
+│  │  (UI Layer) │◄──►│  (Core Engine)    │◄──►│  Config    │  │
+│  └──────┬──────┘    └────────┬─────────┘    └────────────┘  │
+│         │                    │                               │
+│         ▼                    ▼                               │
+│  ┌─────────────┐    ┌──────────────────┐                    │
+│  │  5-Step     │    │  Rust Native     │                    │
+│  │  Wizard     │    │  Modules (.pyd)  │                    │
+│  │  Pages      │    └──────────────────┘                    │
+│  └─────────────┘            │                               │
+│                             ▼                               │
+│  ┌─────────────┐    ┌──────────────────┐    ┌────────────┐  │
+│  │  Embedded   │    │  Windows Service │    │  NSIS      │  │
+│  │  Python 3.14│    │  (Background)    │    │  Installer │  │
+│  └─────────────┘    └──────────────────┘    └────────────┘  │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. Flet GUI (UI Layer)
+
+**File:** `app.py` — `main()` function (lines 6936-9044)
+
+The GUI is built with Flet, a cross-platform UI framework. It provides:
+
+- 5-step wizard interface
+- Sidebar navigation
+- Glass transparency (configurable alpha)
+- Animated transitions
+- Overlay dialogs
+
+**Key Elements:**
+- `ft.Stack` — Root container with overlays
+- `title_bar` — Custom frameless window drag area
+- `sidebar` — Step navigation with status indicators
+- `content_area` — Dynamic content pages
+- `bottom_bar` — Navigation buttons
+
+### 2. InstallerLogic (Core Engine)
+
+**File:** `app.py` — `InstallerLogic` class (lines 2431-5995)
+
+The core engine handles all installation operations:
+
+**Methods:**
+- `download_asset()` — Parallel chunked download with resume
+- `extract_7z()` — 7z archive extraction
+- `install_wsa()` — 6-phase WSA installation
+- `add_playStore()` — 7-phase Play Store integration
+- `uninstall_wsa_logic()` — Complete WSA removal
+- `_adb_connect_loop()` — ADB connection management
+- `_automate_adb_authorization()` — UI automation for ADB popup
+
+**State Dictionary:**
+Contains 40+ keys tracking wizard state, progress, and UI updates.
+
+### 3. ConfigController
+
+**File:** `app.py` — `ConfigController` class (lines 1603-2036)
+
+Manages application configuration with source tracking:
+
+```
+Default Config → Dev Mode Config → Server Config
+```
+
+**Features:**
+- Source-tracked values
+- Validation against allowed types/values
+- Server-side updates via RemoteConfigManager
+
+### 4. RemoteConfigManager
+
+**File:** `app.py` — `RemoteConfigManager` class (lines 2154-2286)
+
+Fetches and applies remote configuration:
+
+**Process:**
+1. Polls server JSON via `widget_ui.pyd`
+2. Validates signature via Rust gateway
+3. Applies configuration changes
+4. Hash-based deduplication
+
+### 5. Background Service
+
+**File:** `app.py` — `WSABackgroundService` (lines 777-1598)
+
+Windows Service running in SYSTEM context:
+
+**Capabilities:**
+- WSA port monitoring (58526)
+- SDK lifecycle management
+- User session process spawning via `CreateProcessAsUserW`
+- Auto-restart on failure
+
+### 6. Native Modules
+
+| Module | Language | Purpose |
+|:-------|:---------|:--------|
+| `widget_ui.pyd` | Rust | Zero-trust config gateway |
+| `playstore_patcher_mem.pyd` | Rust | Play Store patcher SDK |
+
+## Security Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  Security Layers                      │
+├──────────────────────────────────────────────────────┤
+│                                                      │
+│  Layer 1: widget_ui.pyd (Rust)                      │
+│  ├── Zero-trust config gateway                      │
+│  ├── Signature verification                         │
+│  └── Encrypted config parsing                       │
+│                                                      │
+│  Layer 2: Socket-based Instance Locks               │
+│  ├── Single instance enforcement                    │
+│  └── Port-based process detection                   │
+│                                                      │
+│  Layer 3: Windows Service                           │
+│  ├── SYSTEM-level service                           │
+│  ├── Auto-restart on failure                        │
+│  └── User session process spawning                  │
+│                                                      │
+│  Layer 4: Source Protection                         │
+│  ├── Nuitka compilation                             │
+│  ├── PyInstaller bundling                           │
+│  └── Binary string obfuscation                      │
+│                                                      │
+└──────────────────────────────────────────────────────┘
+```
+
+## Build Pipeline
+
+### Primary Build (build.bat)
+
+```
+Step 1: Clean
+    └── Removes dist/, build/, app.pyd
+
+Step 2: Dependencies
+    └── pip install -r requirements.txt
+
+Step 3: Version Update
+    └── PowerShell replaces version in app.py + file_version_info.txt
+
+Step 4: Nuitka Module
+    ├── Compiles app.py → app.pyd (source protection)
+    └── Renames app.py → wsa.py to hide source
+
+Step 5: PyInstaller Onedir
+    ├── Uses WSA_Installer_Download_onedir.spec
+    └── Restores app.py from wsa.py
+
+Step 6: WSARepair.exe
+    └── PyInstaller --onefile
+
+Step 7: Flet Client Patch
+    ├── Patches flet.exe icon + version info
+    └── Creates patched flet-windows.zip
+
+Step 8: NSIS Installer
+    └── Builds WSA_Installer_Setup.exe
+```
+
+## Data Flow
+
+### Installation Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant GUI as Flet GUI
+    participant IL as InstallerLogic
+    participant DL as Download Manager
+    participant EXT as Extractor
+    participant WSA as WSA
+    participant ADB as ADB
+
+    User->>GUI: Click Install
+    GUI->>IL: start_install()
+    IL->>DL: download_asset()
+    DL-->>GUI: progress updates
+    DL->>EXT: extract_7z()
+    EXT->>WSA: install_wsa()
+    WSA-->>IL: installation complete
+    IL->>ADB: add_playStore()
+    ADB-->>IL: Play Store installed
+    IL-->>GUI: step complete
+```
+
+### Configuration Flow
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant CC as ConfigController
+    participant RCM as RemoteConfigManager
+    participant WU as widget_ui.pyd
+    participant Server as Config Server
+
+    App->>CC: load_config()
+    CC->>RCM: fetch()
+    RCM->>WU: load()
+    WU->>Server: HTTPS GET
+    Server-->>WU: JSON config
+    WU-->>RCM: validated config
+    RCM->>CC: apply()
+    CC-->>App: config updated
+```
+
+## File Structure
+
+```
+wsa-installer/
+├── app.py                    # Main application (~11K lines)
+├── run.py                    # Entry point
+├── WSARepair.py              # Windows Settings proxy
+├── patch_flet.py             # Flet client patcher
+├── launcher.cs               # C# launcher
+│
+├── assets/                   # Runtime resources
+│   ├── adb.exe               # ADB binary
+│   ├── AppxManifest.xml      # WSA manifest
+│   ├── Run.bat               # MagiskOnWSALocal launcher
+│   ├── settings.dat          # Pre-patched WSA settings
+│   ├── WsaClient.exe         # Patched WSA client
+│   └── icons/                # Application icons
+│
+├── native/                   # Rust native modules
+│   ├── widget_ui.pyd         # Security gateway
+│   └── playstore_patcher_mem.pyd  # Play Store SDK
+│
+├── emb_py/                   # Embedded Python 3.14
+│   ├── python/               # CPython runtime
+│   ├── PySide6/              # Qt6 bindings
+│   └── requests/             # HTTP client
+│
+├── build/                    # Build scripts
+│   ├── build.bat             # Primary build
+│   ├── build2.bat            # Alternate build
+│   └── WSA_Installer_Setup.nsi  # NSIS script
+│
+├── docs/                     # Documentation
+└── tests/                    # Tests
+```
+
+## Performance Optimizations
+
+### Parallel Downloads
+
+- 30-chunk parallel download system
+- HTTP Range headers for resume support
+- Thread pool executor for concurrent requests
+
+### Caching
+
+- Download cache in `out_asset/cache/`
+- Bundle detection avoids re-downloads
+- Config hash deduplication
+
+### Memory Management
+
+- Streaming subprocess output
+- Queue-based thread communication
+- Lazy loading of heavy components
+
+## Error Recovery
+
+### Retry Logic
+
+- ADB connection: 15 attempts with server restart
+- Download resume: Partial file preservation
+- Process kill: 3-attempt retry loops
+
+### Fallback Mechanisms
+
+- `CreateProcessAsUserW` → `Popen` fallback
+- Server config → default config fallback
+- Bundle → GitHub download fallback
+
+### Logging
+
+- Activity log: `wsa_activity.log`
+- Debug log: `debug.log`
+- UI log box in all dialogs
--- a/Show More
+++ b/Show More