docs: mirror freeunitorg/docs#9 for migration-guide review

[andypost]

Summary

This is a local mirror of freeunitorg#9 so the review feedback there can be addressed as small, reviewable commits before being sent upstream. GitHub MCP access in my environment is scoped to andypost/unit-docs, so the fix iteration happens here.

What was done

• Added upstream = https://github.com/freeunitorg/docs.git and fetched the PR branch (also available as refs/pull/9/head).
• Fast-forwarded master from nginx 6c3106c → freeunitorg 33fd8b9 (479 commits, all from freeunitorg/main). This is the PR's actual base — without it the migration guide has 47 "undefined label" warnings against anchors that freeunitorg defines in new files (community.rst, certificates.rst, etc.) and 1 invalid meta directive ERROR.
• Fast-forwarded claude/review-and-fix-pr-chDsn to the PR tip d5e797d. This branch is now exactly the 3 PR commits on top of master:
  • c513e83 — docs: add migration guide
  • 25575c6 — docs: rewrite migration and installation for FreeUnit fork
  • d5e797d — docker: Build local for test

Both FFs are non-destructive (verified with git merge-base --is-ancestor).

Baseline build numbers (Sphinx 6.2, sphinx-build -E -n)

Commit	Total warnings	In migration.rst
33fd8b9 (master/freeunit main)	9	0
c513e83 (add migration guide)	58	49
25575c6 (rewrite)	56	47
d5e797d (tip)	56	47

The 9 baseline warnings are pre-existing envvar targets on freeunitorg/main — out of scope. The 47 new warnings are the ones the upstream review calls out.

Next commits on this branch

Following the review of freeunitorg#9, subsequent commits on this branch will each address one concern so diffs stay small:

• fix .. meta:: indentation → clears the ERROR.
• escape \*BSD → clears the "inline emphasis" warning.
• rewrite undefined cross-refs (socket, file, user and group, TLS, regex, community, migration-remi-hybrid) → clears ~40 warnings.
• extend short title overlines → 7 warnings.
• wire migration into contents.rst toctree → orphaned-doc warning.
• correct factual claims flagged in review: unitd --version output, ./configure --modules= invalid syntax, unitd --test-config non-existent, make install unitctl claim, pkg/systemd/unit.service missing file, Docker matrix variants that don't exist.
• replace docker-compose v1 with docker compose v2.
• add migration-remi-hybrid section (defines the dangling anchor).
• add Migration Plan and Validation sections per reviewer request.

Verification loop (autonomous)

uv run --python 3.12 --with 'sphinx>=6.2,<8' --with 'docutils>=0.18,<0.20' \
    sphinx-build -E -n -W --keep-going -b nxt_html source build

-W --keep-going gives a non-zero exit on any residual warning and a complete list in one pass, so each fix commit is either clean or obviously regressing.

---

This PR is opened as draft because no fixes have landed yet — it's the starting point for the fix sequence described above.

[andypost]

Despite the successful resolution of the major problems, a few items still need attention:

1. Truncated File and Missing Newline (New Critical Issue): The migration.rst file ends abruptly midsentence ("Module ABI mismatches (especially for"), lacks a terminating newline, and is missing content that should follow. The file needs to be completed and properly terminated.

2. Sitemap Decision: It hasn't been determined whether the new migration.html page should be indexed in the sitemap. The sitemapexclude.txt file should be updated accordingly.

3. Section Adornment Consistency: While not explicitly spotted in this review, the PR's commit message confirms that it resolved "7 titles, 11 overline warnings" by extending underlines. However, a final visual pass of all headings in the raw file is recommended to ensure consistency.

4. Minor Nitpicks: The commit message mentions several factual corrections were made, but some minor details mentioned in the original review (like Nix alias dates, FreeBSD MOVED dates, etc.) should be spot-checked to ensure they were all caught.

The next step should be to fix the truncated file issue, make a final pass on the remaining nits, and then re-request a build to ensure Sphinx runs with zero warnings. Let me know if you'd like me to elaborate on any of these points.