docs: add instructions for Linux and macOS development and testing

Author: DotDev262

CONTRIBUTING.md

@@ -39,6 +39,12 @@ To run the tests, run the following command from the root of the repository:
 dotnet test WinHome.sln
 ```
 
+## 🐧 Linux & 🍎 macOS Development
+
+You can develop and run unit tests for WinHome on Linux and macOS using the .NET 10 SDK. Since the engine is Windows-specific, we use mocks to ensure high test coverage on non-Windows platforms.
+
+For a detailed guide on how to contribute from a non-Windows machine, see the **[Cross-Platform Development Guide](./docs/cross-platform-dev.md)**.
+
 ### Make your changes
 
 Now, go make your changes!

README.md

@@ -221,6 +221,7 @@ Built with modern .NET engineering patterns:
 * **Dependency Injection** (`Microsoft.Extensions.Hosting`)
 * **Strategy Pattern** across package managers
 * **Testable Core** via abstractions (Registry, FS, Processes)
+* **Cross-Platform Dev**: Can be developed/unit-tested on Linux & macOS.
 * **CI/CD** via GitHub Actions (SingleFile & Native builds)
 
 ---

docs/cross-platform-dev.md

@@ -0,0 +1,45 @@
+# Cross-Platform Development Guide
+
+Although WinHome is an "Infrastructure-as-Code tool for Windows," it is built using **modern .NET 10**, allowing developers on **Linux** and **macOS** to contribute to the project effectively.
+
+## 💻 Developing on Linux & macOS
+
+### 1. Prerequisites
+*   **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)**: Required for building and running unit tests.
+*   **[VS Code](https://code.visualstudio.com/)**: With the **C# Dev Kit** extension.
+
+### 2. Building the Project
+You can compile the solution normally on any platform:
+```bash
+dotnet build WinHome.sln
+```
+
+### 3. Running Unit Tests
+Our unit tests are designed with **abstractions and mocks**. This means you can run the logic-heavy unit tests (like config parsing, state management logic, and plugin discovery) without being on Windows:
+```bash
+dotnet test tests/WinHome.Tests/WinHome.Tests.csproj
+```
+
+---
+
+## ⚠️ Platform Limitations
+
+WinHome is a **Windows-native engine**. While the code compiles on other OSs, the core reconciliation logic (`Engine.cs`) contains platform guards:
+
+*   **Registry/Services/WSL**: These modules will be skipped or throw errors if run natively on Linux/macOS.
+*   **Dry-Run**: You can run `dotnet run -- --dry-run` to test configuration parsing and plugin loading, but many modules will log "Skipping: Platform not supported."
+
+---
+
+## 🧪 Testing Windows Logic from Linux/macOS
+
+If you are modifying Windows-specific logic (e.g., the Registry Service) and need to verify it:
+
+### 1. Automated CI (Recommended)
+Push your branch to your fork. Our **GitHub Actions CI** (`test.yaml`) runs on `windows-latest` VMs. It will execute the full suite, including E2E tests, on a real Windows environment.
+
+### 2. Remote Development
+Use the **VS Code Remote - SSH** extension to connect to a Windows machine or VM and develop/debug directly in that environment.
+
+### 3. Windows Containers / VM
+If you have a local Windows machine, you can use the scripts in `test-data/` to run acceptance tests inside a clean Windows Sandbox.

docs/toc.yml

@@ -12,5 +12,7 @@
   href: plugins/toc.yml
 - name: Architecture
   href: architecture/toc.yml
+- name: 🐧 Cross-Platform Development
+  href: cross-platform-dev.md
 - name: Testing Guide
   href: testing.md