Add Editor Integration and WSL Configuration pages

docs/book/v2/editor-integration.md

@@ -0,0 +1,85 @@
+# Editor Integration
+
+## Summary
+
+Connect your editor of choice (VS Code or PhpStorm) directly to your **AlmaLinux 10** environment, and set up Xdebug for step debugging.
+
+> This assumes you've already completed [Setup Packages](setup/setup-packages.md) and have at least one project running under a [virtualhost](virtualhosts/overview.md).
+
+## VS Code (Remote - WSL)
+
+Install the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension in VS Code on Windows.
+
+Then, from inside **AlmaLinux 10**, move to your project's directory and run:
+
+```shell
+code .
+```
+
+This opens VS Code connected to your **AlmaLinux 10** distro - notice the green remote indicator in the bottom-left corner. Every extension, terminal, and file operation now runs using the Linux binaries inside AlmaLinux 10, not the Windows ones, which matters for anything that shells out to `php`, `composer`, or `node`.
+
+> The first time you run `code .` from a new distro, VS Code Server is downloaded and installed automatically inside AlmaLinux 10 - this can take a minute or two.
+
+## PhpStorm (WSL interpreter)
+
+You install PhpStorm normally on Windows, but configure it to use the PHP interpreter inside AlmaLinux 10 instead of installing PHP on Windows.
+
+1. Open your project in PhpStorm.
+2. Go to `Settings` -> `PHP`.
+3. Next to `CLI Interpreter`, click `...` and add a new interpreter.
+4. Choose `From WSL`, select the `AlmaLinux-10` distro, and point it at `/usr/bin/php`.
+5. Confirm and apply.
+
+PhpStorm can now index, run, and debug using the same PHP install the playbook provisioned, instead of a separate Windows copy.
+
+> Your project files are located inside the WSL filesystem (the default and recommended location - see [WSL Configuration](wsl-configuration.md)).
+> You open the project from its `\\wsl.localhost\AlmaLinux-10\...` path in PhpStorm so file watching and indexing stay fast.
+
+## Xdebug
+
+Xdebug isn't installed by the playbook. To add it:
+
+```shell
+sudo dnf install php-pecl-xdebug -y
+```
+
+Then configure it (as root) by editing the Xdebug ini file:
+
+```shell
+sudo nano /etc/php.d/15-xdebug.ini
+```
+
+Add or adjust:
+
+```text
+zend_extension=xdebug.so
+xdebug.mode=debug
+xdebug.start_with_request=yes
+xdebug.client_host=127.0.0.1
+xdebug.client_port=9003
+```
+
+Restart PHP-FPM for the change to take effect:
+
+```shell
+sudo systemctl restart php-fpm
+```
+
+### VS Code
+
+Install the `PHP Debug` extension, then add a `Listen for Xdebug` launch configuration on port `9003`. Start listening, then request your project's URL in the browser - the debugger should stop at your breakpoints.
+
+### PhpStorm
+
+Go to `Settings` -> `PHP` -> `Debug`, confirm the Xdebug port is `9003`, then click the "Start listening for PHP Debug connections" icon in the toolbar and request your project's URL in the browser.
+
+## PHPUnit
+
+Both editors can run PHPUnit using the same WSL-side PHP and Composer install:
+
+* **VS Code**: install a PHPUnit test-runner extension once connected via Remote - WSL, and point it at your project's `vendor/bin/phpunit`.
+* **PhpStorm**: go to `Settings` -> `PHP` -> `Test Frameworks`, add a PHPUnit configuration using the WSL interpreter configured above and your project's `vendor/bin/phpunit`.
+
+## Next step
+
+See [WSL Configuration](wsl-configuration.md) for where to put your project files and how to tune WSL's resource usage, or jump to the [FAQ](faq.md) for common troubleshooting.

docs/book/v2/wsl-configuration.md

@@ -0,0 +1,75 @@
+# WSL Configuration
+
+## Summary
+
+Where to put your project files, how to open them from Windows, how to tune WSL 2's resource usage, and how to back up or move your distro.
+
+## Where to put your project files
+
+Keep your projects inside the WSL filesystem - for example under `/var/www/`, which is exactly where this playbook creates your virtualhosts. Avoid working with projects stored under `/mnt/c/...` (or any other Windows drive mounted into WSL): crossing filesystems this way can significantly slow down file-heavy operations like `composer install`, `npm install`, or a framework's file-watcher.
+
+> If you cloned a project onto `C:\` before setting up WSL, move or re-clone it into your AlmaLinux 10 home directory or `/var/www` instead.
+
+## Opening a WSL project from Windows
+
+To browse your **AlmaLinux 10** files from Windows File Explorer, open:
+
+```text
+\\wsl.localhost\AlmaLinux-10\var\www\
+```
+
+(older WSL versions use `\\wsl$\AlmaLinux-10\...` instead - both work).
+
+From inside AlmaLinux 10, you can also open the current directory in Windows File Explorer directly:
+
+```shell
+explorer.exe .
+```
+
+## `.wslconfig`
+
+WSL 2 runs inside a lightweight VM, and by default it can use most of your machine's memory and grow its virtual disk indefinitely. You can cap this with a `.wslconfig` file at `C:\Users\<your-windows-username>\.wslconfig` (created from Windows, not inside AlmaLinux 10):
+
+```text
+[wsl2]
+memory=8GB
+processors=4
+swap=2GB
+vmIdleTimeout=60000
+networkingMode=mirrored
+```
+
+* `memory` / `processors`: cap how much RAM/CPU the WSL VM can use.
+* `swap`: swap file size inside the VM.
+* `vmIdleTimeout`: milliseconds of inactivity before the VM is torn down (frees memory when you're not using WSL).
+* `networkingMode=mirrored`: mirrors your Windows network interfaces into WSL, which can fix some VPN/corporate-network connectivity issues.
+
+Apply changes with:
+
+```shell
+wsl --shutdown
+```
+
+then reopen **AlmaLinux 10**.
+
+> The VM's virtual disk (VHDX) only grows - it doesn't shrink automatically as you delete files. See Microsoft's guide on compacting a WSL disk if it grows larger than expected.
+
+## Backup and portability
+
+`wsl --unregister AlmaLinux-10` (documented in [Install AlmaLinux 10](setup/installation.md)) deletes the distro and everything in it - it's a reset, not a backup.
+
+To back up or move your environment instead, export it to a single file:
+
+```shell
+wsl --export AlmaLinux-10 alma-linux-10-backup.tar
+```
+
+And restore it (to the same machine or a different one) with:
+
+```shell
+wsl --import AlmaLinux-10 C:\WSL\AlmaLinux-10 alma-linux-10-backup.tar
+```
+
+## Next step
+
+See [Editor Integration](editor-integration.md) to connect VS Code or PhpStorm, or jump to the [FAQ](faq.md) for common troubleshooting.

mkdocs.yml

@@ -18,6 +18,8 @@ nav:
       - Virtualhosts:
           - Overview: v2/virtualhosts/overview.md
           - Create virtualhost: v2/virtualhosts/create-virtualhost.md
+      - Editor Integration: v2/editor-integration.md
+      - WSL Configuration: v2/wsl-configuration.md
       - FAQ: v2/faq.md
   - v1:
       - Terminal: v1/terminal.md