updated v2 folder

Author: bidi47

docs/book/v2/setup/installation.md

@@ -1,10 +1,20 @@
 # Install AlmaLinux 10 on WSL 2
 
+## Summary
+
+Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account.
+
 > If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/).
 
+> This is step 2 of 3: [System Requirements](system-requirements.md) → **Install AlmaLinux 10** (this page) → [Setup Packages](setup-packages.md).
+
+> All commands on this page are executed in `Windows Terminal`, on your Windows host — not inside AlmaLinux 10.
+
 Before proceeding with the installation, we need to make sure that no other WSL 2 distribution (aka: _distro_) is running.
 This is important because this installation will fail if required ports are already in use by another distro.
 
+> The distro is downloaded over the internet, so make sure you have a stable connection. Depending on your connection speed, the download can take anywhere from a couple of minutes to significantly longer.
+
 Open `Windows Terminal`.
 
 ## Stop other WSL 2 distros
@@ -32,7 +42,7 @@ If you have other distros installed, the output could look similar to the below:
 ```
 
 Make sure that the **STATE** column reads **Stopped** for all distros.
-If any of them reads **Running**, you must stop if first by executing `wsl -t <distro-name>` after replacing `<distro-name>` with the name of the distro you want to stop.
+If any of them reads **Running**, you must stop it first by executing `wsl -t <distro-name>` after replacing `<distro-name>` with the name of the distro you want to stop.
 Once you have stopped all distros, you can continue to the [installation](#install-almalinux-10) section.
 
 ## Install AlmaLinux 10
@@ -126,3 +136,49 @@ Finally, you should see the following message:
 passwd: password updated successfully
 [<your-alma-linux-10-username>@<your-device-name> <your-windows-username>]$
 ```
+
+> At this point your terminal has dropped you inside the **AlmaLinux 10** shell (notice the prompt changed). Keep this window open and continue directly with [Setup Packages](setup-packages.md) — its commands run inside AlmaLinux 10, not in Windows Terminal. If you close this window, see [Running on WSL 2](../running.md) to reconnect.
+
+## Next step
+
+Continue to [Setup Packages](setup-packages.md) to install the required system packages and provision your development environment.
+
+## FAQ
+
+### What if the installation fails because a distro is already running?
+
+Make sure no other WSL 2 distro is running by checking `wsl -l -v` — all distros must show **Stopped**. Stop any running distro with `wsl -t <distro-name>` before retrying the installation.
+
+### What if `AlmaLinux-10` is already installed?
+
+The installation will fail with `A distribution with the supplied name already exists`. Use a different `--name` value, or remove the existing distro first if you intend to reinstall it.
+
+### Does the username need to match my Windows username?
+
+No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username.
+
+### What if I get a `BAD PASSWORD` message?
+
+This is just a strength warning. Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it.
+
+### Where can I find the list of available distros if `AlmaLinux-10` isn't shown?
+
+Run `wsl --list --online` to see the current list of installable distros and their **NAME** values.
+
+### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error?
+
+This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled — revisit the [System Requirements](system-requirements.md) page and confirm both. A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall.
+
+### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)?
+
+You don't need the Store for this step — `wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store.
+
+### How do I completely remove AlmaLinux-10 and start over?
+
+Unregister the distro, which deletes it and all its data, then reinstall it from scratch:
+
+```shell
+wsl --unregister AlmaLinux-10
+```
+
+Once unregistered, you can run `wsl --install -d AlmaLinux-10` again as described above.

docs/book/v2/setup/setup-packages.md

@@ -1,13 +1,23 @@
 # AlmaLinux 10 Setup
 
+## Summary
+
+Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment.
+
 > The instructions below also work without using WSL.
 
+> This is step 3 of 3: [System Requirements](system-requirements.md) → [Install AlmaLinux 10](installation.md) → **Setup Packages** (this page).
+
+> All commands on this page are executed **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. This is the same session left open at the end of the [installation](installation.md) step — if you closed it, see [Running on WSL 2](../running.md) to reconnect first.
+
 Update/Upgrade system packages:
 
 ```shell
 sudo dnf upgrade -y
 ```
 
+> This step downloads packages over the internet and can take a few minutes depending on your connection speed and how many updates are pending.
+
 You should see the below message, shown the first time you execute a command which requires elevated permissions (hence the `sudo` modifier at the beginning of the command).
 
 ```text
@@ -31,6 +41,8 @@ Install system packages:
 sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y
 ```
 
+> `$(rpm -E %almalinux)` resolves to your AlmaLinux major version (`10`), so this installs the matching Remi repository release package. `dnf` verifies the package's GPG signature before installing it, same as any other package.
+
 Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections:
 
 ```shell
@@ -41,6 +53,8 @@ sudo dnf install ansible-core -y
 ansible-galaxy collection install community.general community.mysql
 ```
 
+> Both of the above require internet access to download packages/collections from their respective repositories (dnf repos and Ansible Galaxy). If either command fails or times out, check your network connection first.
+
 Move inside your home directory (it is `/home/` followed by your **AlmaLinux 10** username, for example: `/home/dotkernel`):
 
 ```shell
@@ -65,7 +79,13 @@ Duplicate `config.yml.dist` as `config.yml`:
 cp config.yml.dist config.yml
 ```
 
-Using your preferred text editor, open `config.yml` and fill in the empty fields.
+Using your preferred text editor, open `config.yml` and fill in the empty fields:
+
+* `config.git.config."user.name"` / `"user.email"`: the identity Git will use for your commits inside AlmaLinux 10.
+* `config.mariadb.root_password`: the password to set for MariaDB's `root` user — you'll use this to log into phpMyAdmin later.
+* `config.system.username`: defaults to your current AlmaLinux 10 username automatically, usually no change needed.
+* `config.virtualhosts`: a list of local domains to create virtualhosts for (see [Virtualhosts](../virtualhosts/overview.md)); the default entry `example.localhost` can be removed or left as-is.
+
 Save and close the file.
 
 Install components by running the below Ansible command:
@@ -87,3 +107,33 @@ Once finished, check if everything works by opening in your browser:
 The installation is complete, your **AlmaLinux 10** development environment is ready to use.
 
 > If you are using WSL 2, restart your `Windows Terminal` to find a new option in the tab selector, called **AlmaLinux-10**; clicking it will open a new tab connected to **AlmaLinux 10**.
+
+## Next step
+
+Your environment is now provisioned. Continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Virtualhosts](../virtualhosts/overview.md) to host your first project.
+
+## FAQ
+
+### What if `config.yml` doesn't exist yet?
+
+Duplicate the provided template by running `cp config.yml.dist config.yml`, then fill in the empty fields before running the playbook.
+
+### What if the Ansible playbook fails partway through?
+
+Review the summary output for the failed task, fix the underlying issue (for example a misconfigured field in `config.yml`), and re-run `ansible-playbook -i hosts install.yml --ask-become-pass` — it is safe to re-run.
+
+### What if `ansible-galaxy collection install` fails or times out?
+
+This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. Check your connection and re-run the command — it's safe to run again even if some collections already installed successfully.
+
+### What if `http://localhost/` doesn't load after installation?
+
+If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running.
+
+### How do I log into phpMyAdmin?
+
+Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`.
+
+### Can I run this setup without WSL?
+
+Yes, the instructions work the same way on a non-WSL AlmaLinux system — just skip the WSL-specific notes.

docs/book/v2/setup/system-requirements.md

@@ -1,14 +1,36 @@
-# System requirements for AlmaLinux 10 on WSL 2
+# System Requirements for AlmaLinux 10 on WSL 2
+
+## Summary
+
+Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version.
 
 > If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/).
 
+> This is step 1 of 3 in setting up your development environment: **System Requirements** (this page) → [Install AlmaLinux 10](installation.md) → [Setup Packages](setup-packages.md).
+
+> All commands on this page are executed in `Windows Terminal`, on your Windows host — not inside AlmaLinux 10.
+
+## Minimum requirements
+
+Before installing WSL 2, make sure your machine meets the following:
+
+* Windows 10 version 1903 (build 18362) or higher, or Windows 11.
+* A 64-bit processor with Second Level Address Translation (SLAT) support.
+* Hardware virtualization enabled in your system's BIOS/UEFI (sometimes called `Intel VT-x`, `AMD-V`, or `SVM Mode`).
+* At least 4 GB of RAM (8 GB or more recommended for running a full development stack comfortably).
+* A few GB of free disk space for the distro plus additional space for your projects and databases.
+
+For the full, up-to-date list, see Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites).
+
+## Check your WSL version
+
 Open `Windows Terminal` and execute the following command:
 
 ```shell
 wsl -v
 ```
 
-The output should look similar to this:
+The output should look similar to this (your version numbers will likely differ):
 
 ```text
 WSL version: 2.2.4.0
@@ -21,12 +43,11 @@ Windows version: 10.0.22631.3737
 ```
 
 If the output starts with `WSL version: 2.x.x.x`, you are ready to use WSL 2 and can proceed to [install AlmaLinux 10](installation.md).
+If it doesn't (for example it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below.
 
 ## Install WSL 2
 
-Before proceeding with the installation, please consult Microsoft's [documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites) regarding the minimum requirements for running WSL 2.
-
-Once you identified that your machine can run WSL 2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`.
+Once you've confirmed your machine meets the [minimum requirements](#minimum-requirements) above, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`.
 This will open a window where you can turn Windows features on/off.
 Make sure that the below features are activated (checked):
 
@@ -46,10 +67,22 @@ Make sure that version `2` of WSL is set as default by executing the below comma
 wsl --set-default-version 2
 ```
 
-To test, run again the following command:
+Run `wsl -v` again — this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md).
 
-```shell
-wsl -v
-```
+## FAQ
+
+### What if `wsl -v` shows WSL version 1 instead of 2?
+
+Run `wsl --set-default-version 2` and then re-run `wsl -v` to confirm the version has switched.
+
+### What if the `OptionalFeatures` dialog doesn't show all required features?
+
+Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above.
+
+### Do I need to restart my computer after enabling the Windows features?
+
+Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect.
+
+### What if my machine doesn't meet the minimum requirements for WSL 2?
 
-This time the output should display `WSL version: 2.x.x.x`, which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md).
+Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI — this is the most common blocker. If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites).