[docs][P2] TROUBLESHOOTING.md: missing section for multi-distro install failures (Void Linux xbps, Alma, Fedora, Oracle Linux)

[FabioLeitao]

docs token | thin slice | Composer 2

Context

Data Boar is tested against: Ubuntu, Debian, Alma Linux, Fedora, OpenSUSE, Oracle Linux, and Void Linux (xbps). The current TROUBLESHOOTING.md covers Docker + connectivity + credentials well, but has no section for install-time failures on non-Debian distros.

This is especially relevant because:

• mariadb PyPI connector requires libmariadb-dev (Debian/Ubuntu: apt) but different names on other distros
• Void Linux uses xbps-install (not apt, dnf, or zypper) and package names differ
• MySQL/MariaDB library availability varies across distros (confirmed intentional multi-driver approach in pyproject.toml)
• Completão/Maestro runs scans on heterogeneous lab nodes

What to add

Add a new section to docs/TROUBLESHOOTING.md (after Docker section):

## Install-time failures on non-Debian Linux distributions

Data Boar targets multiple Linux distributions. System library requirements differ by distro.

### Required system libraries (distro map)

| Library purpose | Debian/Ubuntu | Fedora/Alma/RHEL/Oracle | OpenSUSE | Void Linux |
|---|---|---|---|---|
| PostgreSQL client | `libpq-dev` | `postgresql-devel` | `postgresql-devel` | `postgresql-libs` |
| MariaDB/MySQL client | `default-libmysqlclient-dev` | `mariadb-devel` | `mariadb-devel` | `libmariadbclient` |
| ODBC | `unixodbc-dev` | `unixODBC-devel` | `unixODBC-devel` | `unixodbc-devel` |
| SSL/TLS | `libssl-dev` | `openssl-devel` | `libopenssl-devel` | `openssl-devel` |

### Void Linux (xbps)
```bash
sudo xbps-install -S postgresql-libs libmariadbclient unixodbc-devel openssl-devel pkg-config
uv sync

Fedora / Alma / RHEL / Oracle Linux (dnf)

sudo dnf install -y postgresql-devel mariadb-devel unixODBC-devel openssl-devel pkg-config gcc
uv sync

OpenSUSE (zypper)

sudo zypper install -y postgresql-devel mariadb-devel unixODBC-devel libopenssl-devel pkg-config gcc
uv sync

If uv sync fails with a compilation error, check the error for the missing library name and install the corresponding -devel package.

Also add a row to the "Deep-dive documentation" table:

```markdown
| **Multi-distro install** | System library requirements for non-Debian distros (Void, Fedora, Alma, OpenSUSE, Oracle Linux) | (this section, above) | — |

Ritual

1. Verify package names on Void Linux against xbps-query -Rs mariadb output (lab node)
2. Add section to TROUBLESHOOTING.md (EN) and TROUBLESHOOTING.pt_BR.md (pt-BR)
3. Gate: .\scripts\lint-only.ps1
4. Commit: docs(troubleshooting): add multi-distro install troubleshooting section

Out of scope

Do not change any Python code or pyproject.toml. Documentation only.

[FabioLeitao]

2 modos de falha de onboarding confirmados (pipx real, 2026-07-09)

Testei a porta do usuário (pipx install data-boar), não só venv. O venv (py3.12 forçado + build-deps) mascarava 2 falhas que o pipx-real expõe:

1. RHEL9-family (Alma/Rocky/Oracle 9): python default 3.9 < requires-python 3.12
Repro (almalinux:9, python3 = 3.9.25):

$ pipx install data-boar
ERROR: Ignored the following versions that require a different python version: 1.7.4.post2 Requires-Python >=3.12
ERROR: No matching distribution found for data-boar

Sugestão de troubleshooting:

sudo dnf install -y python3.12
pipx install --python python3.12 data-boar

2. Alpine/musl: sem toolchain → sklearn compila → metadata-generation-failed
Repro (alpine:3.23, apk add pipx sozinho):

$ pipx install data-boar
... Running `pgcc --version` gave "No such file or directory"
error: metadata-generation-failed

scikit-learn não tem wheel musllinux → tenta compilar, mas o env do pipx não tem compilador. Sugestão:

apk add build-base gfortran openblas-dev
pipx install data-boar

(ou aguardar o wheelhouse musllinux prebuilt — #929.)

(RO-auditor. Debian/Fedora com python>=3.12 = pipx frictionless.)

[FabioLeitao]

Closed: shipped via #1175 (backlog hygiene sweep, dangling — PR não usou Closes-keyword na época).