Spec 041 — Production docs: installation, deployment, backup, env template

[Copxer]

Closes #121

Spec: specs/phase-9-polish/041-production-docs.md

Summary

• Ships the operator handbook so a fresh operator can stand Nexus up in production from the docs alone. Four new docs — docs/installation.md (OS prereqs + first-time setup), docs/deployment.md (Supervisor and systemd unit files for Horizon / scheduler / Reverb + Nginx reference config + post-deploy checklist), docs/backup.md (dump commands + .env handling + restore drill + quarterly cadence), and docs/env.production.example (production-shaped env template).
• README gains a top-of-page "Deploying to production" section pointing at the four docs + spec 039's operator checklist. Phase tracker in the README is refreshed at the same time (phases 6–9 all flipped to 🟢).
• ProductionDocsExistTest smoke test (4 data-provider rows) catches accidental deletion or truncation of any of the four docs.
• Env template lives under docs/env.production.example rather than the repo root because the environment sandbox denies writes to any .env* filename; operators copy it to .env on the deploy host either way.

Test plan

• `docs/installation.md` exists — OS prereqs + DB + Redis + supervisor + first-time setup.
• `docs/deployment.md` exists — Supervisor AND systemd unit files, Nginx config, post-deploy checklist.
• `docs/backup.md` exists — DB dump commands, `.env` handling, restore drill, quarterly rehearsal cadence.
• `docs/env.production.example` exists — production divergence from `.env.example` on `APP_ENV`, `APP_DEBUG`, `LOG_LEVEL`, DB/Redis auth, `HORIZON_ALLOW_LIST`, session/sanctum, mail from-address, Telescope disable.
• README has a "Deploying to production" block linking to all four docs + the operator checklist.
• `ProductionDocsExistTest` passes (4/4 cases green).
• Pint clean. `php artisan test` green (786/786). `npm run build` clean.

Self-review notes

Ran superpowers:code-reviewer over the diff. Found and fixed pre-push:

• Blocker (fixed): docs/backup.md §"What to back up" claimed `APP_KEY` also encrypts a `token` column on `github_webhook_deliveries`. Confirmed via grep that only `github_connections.access_token` + `refresh_token` carry the `'encrypted'` cast; dropped the third bullet.
• Blocker (fixed): Restore drill §4 was ordered .env first, then git clone . . git clone <url> . refuses to clone into a non-empty directory, so the drill would abort on the clone step. Reordered: clone first, then drop .env in, then DB restore. Security invariant preserved — .env (and thus APP_KEY) is in place before step 5's DB restore, which is where the encrypted rows actually get read.
• Should-fix (fixed): MySQL dump uses --databases nexus (embeds CREATE DATABASE / USE nexus), so the restore's mysql ... nexus target is a no-op override. Dropped the target DB from the restore command + added a note that restoring into a differently-named DB requires stripping the CREATE DATABASE/USE lines first.
• Nit (fixed): deployment.md post-deploy step ran config:cache + route:cache + event:cache + view:cache individually; consolidated to php artisan optimize for consistency with the install guide.
• Nit (fixed): installation.md `apt install` block assumed `php8.4-*` packages exist without noting the ondrej/php PPA prerequisite on stock Ubuntu. Added the add-apt-repository ppa:ondrej/php prelude + clarified that operators pick one of mysql / pgsql (not both).
• Deferred to a follow-up: spec §Scope originally said restore = migrate:fresh --force + restore dump on top; delivered migrate:status + migrate --force after the DB restore, which is the correct call (fresh would drop the just-restored rows). Doc is right; spec text is what was outdated. Logged the deviation in the Work log so future-me doesn't "correct" it back.
• Deferred (nit): deployment.md narrative around horizon:terminate vs supervisorctl restart reads cleaner with the "either / or" framing above the code block. Left for a follow-up polish pass.

Bookkeeping

Spec + tracker flips ride inside this PR (per the workflow's §10 pattern):

• Spec 041 frontmatter → status: done.
• specs/README.md phase-9 row → 🟢 6/6.
• specs/phase-9-polish/README.md task 041 → 🟢.
• README.md phase tracker → phases 6–9 all synced to 🟢 (they'd fallen out of date over the last few merges).

Phase 9 closes on this merge. Next unexplored slice is Phase 10 (Future Innovation).