GRM-117: fix: fix wiki link URLs, heading hierarchy, quote pip install vars

docs/user/faq.md

@@ -1,6 +1,6 @@
 # FAQ
 
-### How do I obtain the Gitea registration token?
+## How do I obtain the Gitea registration token?
 
 There are three levels of registration tokens, depending on which repositories the runner should serve:
 
@@ -10,7 +10,7 @@ There are three levels of registration tokens, depending on which repositories t
 
 Set the token as `GITEA_REGISTRATION_TOKEN` in your `.env` file or pass it via `--token` on the command line.
 
-### What is the CI_GITEA_TOKEN and do I need it?
+## What is the CI_GITEA_TOKEN and do I need it?
 
 `CI_GITEA_TOKEN` is a Gitea admin API token used for optional post-install verification. When set, GRM queries the Gitea API after installation to confirm the runner appears in the runner list. This is purely informational — the integration test passes/fails based on the `.runner` file and systemd service, not the API check.
 
@@ -18,7 +18,7 @@ To generate one: Settings → Applications → Generate New Token, with the `adm
 
 If you skip it, GRM will still verify the runner correctly — it just won't show the extra API confirmation.
 
-### How do I skip the sudo password prompt for automation?
+## How do I skip the sudo password prompt for automation?
 
 Configure passwordless sudo on the remote host and pass `--no-ask-become-pass` to the CLI command. This is recommended for CI/CD pipelines.
 
@@ -34,7 +34,7 @@ Then use:
 grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner --no-ask-become-pass
 ```
 
-### Can I run multiple runners on the same host?
+## Can I run multiple runners on the same host?
 
 Yes. Each runner instance is fully isolated with its own system user (`grm-<name>`), rootless Docker daemon, data directory, and systemd user service. Install additional runners with different `--name` values and manage them independently by name.
 
@@ -46,7 +46,7 @@ grm list
 
 Runners on the same host never interfere with each other or with the host's Docker installation.
 
-### Why does my runner appear offline after installation?
+## Why does my runner appear offline after installation?
 
 Check that `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` are correct, verify the runner service is running with `sudo -u grm-<name> systemctl --user status gitea-runner`, and check the logs for registration errors. You can also confirm the runner appears as **Online** in the Gitea UI under **Actions → Runners**.
 
@@ -56,15 +56,15 @@ Common causes:
 - Rootless Docker daemon not running — check `sudo -u grm-<name> systemctl --user status docker`
 - Lingering not enabled — check `loginctl show-user grm-<name> | grep Linger`
 
-### What does the "Event loop is closed" warning mean?
+## What does the "Event loop is closed" warning mean?
 
 This is a harmless cleanup traceback from Molecule's Docker driver when the test process is interrupted. It does not indicate a test failure.
 
-### Where are runner connection details stored?
+## Where are runner connection details stored?
 
 GRM stores each runner's connection details (host, user, SSH key, Gitea URL, labels) in a local JSON registry at `~/.local/share/grm/runners.json`. After installation, lifecycle commands work by runner name only — you can override any stored value by passing the corresponding flag.
 
-### How do I update the gitea_runner binary?
+## How do I update the gitea_runner binary?
 
 Use the `grm update` command:
 
@@ -80,7 +80,7 @@ grm update 192.168.1.10 --user ubuntu --version 1.0.8
 
 The update command downloads the new binary and replaces the existing one at `/usr/local/bin/gitea_runner`. The runner service is restarted automatically.
 
-### How do I completely remove a runner?
+## How do I completely remove a runner?
 
 Use the `grm remove` command:
 
@@ -96,18 +96,18 @@ If the remote host is already gone or unreachable, use `--force` to skip remote
 grm remove prod-runner --force
 ```
 
-### What is the difference between disable and remove?
+## What is the difference between disable and remove?
 
 - **`grm disable <name>`** — Deregisters the runner from Gitea and stops the service, but leaves the user, directories, and service files in place. The runner can be re-enabled later with `grm enable` and re-registered with a new token.
 - **`grm remove <name>`** — Completely removes the runner: deregisters from Gitea, stops and disables the service, removes the system user, deletes all directories, and removes the local registry entry. This is irreversible.
 
-### What operating systems are supported?
+## What operating systems are supported?
 
 GRM supports Arch Linux (rolling), Ubuntu 22.04/24.04, and Debian 12. All supported OSes are tested in CI via Molecule scenarios on every PR that changes Ansible files.
 
-### How do I change the UI language?
+## How do I change the UI language?
 
-Set the `GRM_LANG` environment variable to one of the supported languages: `en` (English, default), `bg` (Bulgarian), `de` (German), `ru` (Russian), `zh` (Chinese).
+Set the `GRM_LANG` environment variable to one of the supported languages: `en` (English, default), `bg` (Bulgarian), `de` (German), `ru` (Russian), `zh` (Chinese), `pl` (Polish).
 
 ```bash
 GRM_LANG=bg grm install 192.168.1.10 --user ubuntu --name prod-runner
@@ -119,7 +119,7 @@ Or set it in your `.env` file:
 GRM_LANG=bg
 ```
 
-### How do I enable debug logging?
+## How do I enable debug logging?
 
 Set the `GRM_LOG_LEVEL` environment variable to `DEBUG`:
 
@@ -129,7 +129,7 @@ GRM_LOG_LEVEL=DEBUG grm install 192.168.1.10 --user ubuntu --name prod-runner
 
 The log file at `~/.local/state/grm/logs/grm.log` always captures DEBUG level regardless of this setting. Ansible execution logs are stored in timestamped files at `~/.local/state/grm/logs/ansible-<timestamp>.log`.
 
-### What runner labels should I use?
+## What runner labels should I use?
 
 By default, runners are registered with `docker,ubuntu-latest:docker://runner-images:ubuntu-22.04`. You can override this with `--labels` or the `GITEA_RUNNER_LABELS` environment variable.
 
@@ -142,7 +142,7 @@ grm install 192.168.1.10 --user ubuntu --name prod-runner \
   --labels "docker:docker://gitea/runner-images:ubuntu-latest"
 ```
 
-### Is GRM secure?
+## Is GRM secure?
 
 Yes. GRM is designed with security as a first-class concern:
 
@@ -151,7 +151,7 @@ Yes. GRM is designed with security as a first-class concern:
 - **No shell injection**: The CLI never uses `shell=True` with subprocess.
 - **Bandit security scan**: The CI pipeline runs Bandit on every PR.
 
-### Can I install GRM via pip?
+## Can I install GRM via pip?
 
 Yes:
 
@@ -161,7 +161,7 @@ pip install gitea-runner-manager
 
 This installs the `grm` CLI and its Python dependencies. The Ansible playbooks and role are bundled with the package. For development or access to Make targets, clone the repository instead.
 
-### How does GRM handle idempotence?
+## How does GRM handle idempotence?
 
 The Ansible role is idempotent — running `grm install` twice produces zero changes on the second run. Each task checks for existing state before making changes. For example: