docs: restructure UPGRADE.md into operator and developer guides

[turegjorup]

Summary

Restructures the 2.x → 3.0 upgrade guide by audience, assuming #495 (app:utils:convert-env-to-3x) ships in 2.8.

Features Added

• Operator / developer split: operators get a step-by-step upgrade path; developers get repository-merge, external-template conversion and removed-feed-type notes.
• Application config vs. infra config: the operator guide separates config migration (step 1) from infrastructure (step 2). Config migration is now driven by 2.8's app:utils:convert-env-to-3x, which converts the loaded env and the admin/client config.json in one pass — the full APP_* rename table is replaced by a collapsed manual fallback stating the rename rule and its exceptions.
• Four hosting options in the infra step:
  • A — os2display-docker-server: follow the upgrade instructions in that repo (task env:migrate / task env:diff).
  • B — published GHCR images, own container orchestration: env_file: pattern, volumes for config/jwt/ + public/media/, nginx/PHP runtime tuning, auto-shipped release.json.
  • C — GitHub build artifacts, classic nginx setup: the pre-built release tarball + checksum from GitHub releases; no Composer/Node on the host, release.json included.
  • D — bare metal, repo checked out: prod composer install, npm run build, nginx reference config, hand-written release.json.
• app:update-based content migration: step 3 uses app:update --no-interaction instead of the individual template/screen-layout install commands, with the list commands kept for inspection.
• Checklists: pre-upgrade checklist (on 2.x), required-.env.local sanity check, post-upgrade sanity checks, and a template-conversion checklist.
• The repository is referenced by its current name throughout — the rename is not decided; the guide will be updated if it happens.

Files Changed

• UPGRADE.md — restructured as above; no upgrade step was dropped (migration rollup, template/layout install via app:update, deprecated feed-source cleanup and screen auto-upgrade are all retained, condensed)
• CHANGELOG.md — entry under [Unreleased]

Test Plan

• npx markdownlint-cli UPGRADE.md CHANGELOG.md — clean
• Verified all intra-repo links/anchors (#custom-templates, #configuration, #development-setup, #taskfile) and the TOC anchors exist on release/3.0.0
• Commands referenced (app:update, app:feed:remove-deprecated-feed-sources, app:templates:*, app:screen-layouts:*) verified present on release/3.0.0
• Option C verified against .github/workflows/github_build_release.yml (tarball contents, checksum, release.json locations)

🤖 Generated with Claude Code

[tuj]

LGTM.
Minor issues raised by AI review. No blockers imo.

---

AI Review

Verdict: Strong improvement over the linear guide — role split, four hosting-options matrix, and pre/post-upgrade checklists are exactly what a 3.0 migration needs. Coherent with #495 (uses the new convert-env-to-3x converter as the canonical path).

Genuine fixes the PR slips in:

• APP_HTTP_CLIENT_LOG_LEVEL → LOG_LEVEL_OUTBOUND_HTTP (old guide had it staying as HTTP_CLIENT_LOG_LEVEL — wrong).
• The APP_ACTIVATION_CODE_EXPIRE_INTERNAL typo is finally named out loud.

Issues:

1. Pre-upgrade checklist asks operators to "check for feed sources using removed feed types" but the command for that only appears in Step 3 — add the dry-run invocation (or a forward-link) to the checklist itself.

2. Manual fallback rename list shrank from ~50 explicit lines to a verbal rule + 3 exceptions. Either keep the full table inside the <details> block or point at src/Command/Utils/ConvertEnvTo3xCommand.php::ENV_MAP as the source of truth.

3. Step 3 runs doctrine:migrations:rollup then app:update — correct, but a one-line "the rollup makes the migrate phase a no-op" prevents reader confusion.

   The flow is:

   1. doctrine:migrations:rollup --no-interaction
   2. app:update --no-interaction (which itself runs doctrine:migrations:migrate)

   After step 1 the consolidated migration is recorded as executed, so step 2's migrate phase is effectively a no-op and only the template/layout install runs. That's the intended behaviour but a passing reader might worry "I just rolled up — won't app:update redo migrations?" A one-line "the rollup makes the migrate phase a no-op; templates and layouts install in this step" would close that gap.

4. Post-upgrade sanity checks don't include "an existing screen reconnects without re-pairing" — the cheapest single check for a JWT keypair/passphrase mismatch.

   The guide repeatedly says "reuse the 2.x keypair and JWT_PASSPHRASE," which is correct. The post-upgrade sanity checks include /admin login but not an explicit check that a 2.x-issued token still validates or that screen JWTs still work. A line like "[ ] An existing screen reconnects without re-pairing" would catch a keypair/passphrase mismatch directly.

5. Option C tarball extraction — depending on whether the tarball has a top-level dir, the suggested tar -xzf … -C /var/www/display either lands cleanly or creates a nested dir; document the layout or use --strip-components=1.