docs: restructure 1.x → 3.x upgrade around the 2.8 config converter

[turegjorup]

Summary

Reworks the 1.x → 3.x UPGRADE.md so the configuration migration is driven by the API's app:utils:convert-env-to-3x command (run on the 1.x stack via task upgrade_prep from #43, producing env.3x) instead of the sed-based env:migrate. Follows the pattern and tone of upstream display-api-service#496, of which this repo is the "Option A" target.

Also folds in the four MariaDB upgrade gaps surfaced in review.

Pairs with #43 (the final 1.x release that adds task upgrade_prep). The guide references env.3x and that task by name.

Features Added

• Converter-first env migration. New "Pre-upgrade checklist (while still on 1.x)" exports the running configuration before the stack is stopped (the converter reads the live app + admin/client config.json). The sed rename is demoted to a <details> fallback for pre-2.8 installs.
• env:migrate prefers env.3x. When present, it splits off the trailing infrastructure advisory (COMPOSE_*/PHP_*/NGINX_*/MARIADB_*) into .env.symfony.infra-advisory and writes the rest to .env.symfony.migrated; otherwise it falls back to the sed conversion of a 1.x .env.docker.local.
• #496-style structure — table of contents and checkbox checklists.

MariaDB gaps folded in

• MARIADB_AUTO_UPGRADE=1 on the mariadb service — the 10.x → 11.4 system-table upgrade now runs automatically on first boot against the carried-over data (also refreshes the healthcheck user, rescuing pre-2023 data dirs). Corrects the old "auto-runs on first start" claim.
• stop_grace_period: 1m on the mariadb service — no SIGKILL mid-flush before the major cut; the guide also verifies the 10.x server shut down cleanly.
• rm -f docker-compose.yml before git checkout — 1.x leaves an untracked generated compose file that otherwise blocks the checkout.
• Data-volume / COMPOSE_PROJECT_NAME continuity check — so a mismatched project name can't silently boot an empty database.

Files Changed

• UPGRADE.md — restructured as above; no step dropped (backups, MariaDB upgrade, first boot, validation, rollback all retained).
• docker-compose.yml — MARIADB_AUTO_UPGRADE=1 + stop_grace_period: 1m on the mariadb service.
• Taskfile.yml — env:migrate env.3x-aware with sed fallback.
• .gitignore — ignore secret-bearing migration intermediates (env.3x, .env.symfony.migrated, .env.symfony.infra-advisory).
• README.md — env:migrate task description + MariaDB major-upgrade FAQ updated for auto-upgrade.
• CHANGELOG.md — entries under [Unreleased] — release/3.0.0.

Test Plan

• docker compose config renders MARIADB_AUTO_UPGRADE: "1" and stop_grace_period: 1m0s on the mariadb service (profile active).
• task env:migrate exercised both ways: with an env.3x fixture (splits app env from advisory) and without (sed fallback on a synthetic .env.docker.local).
• task --list parses; scripts/check-tasks-readme.sh passes (README task block in sync).
• markdownlint (repo's pinned image + config) clean on UPGRADE.md, README.md, CHANGELOG.md.
• All UPGRADE.md table-of-contents anchors verified to resolve to their headings.

🤖 Generated with Claude Code