feat: add Nginx to Caddy migration toolkit with scripts and usage guide

setup/nginx-to-caddy/USAGE_GUIDE.md

@@ -0,0 +1,95 @@
+# Usage Guide: Nginx to Caddy Migration
+
+This guide helps you migrate safely without big-bang risk.
+
+## 1) Collect Nginx inventory
+
+Run from your admin machine:
+
+```bash
+cd setup/nginx-to-caddy
+./extract_nginx_inventory.sh --host=<nginx-host-ip> --user=<ssh-user> --port=22 --yes
+```
+
+You will get:
+- `output/nginx-full.conf`
+- `output/etc-nginx.tar.gz`
+- `output/inventory-summary.txt`
+
+## 2) Generate initial Caddyfile
+
+For Cloudflare DNS-01 flow:
+
+```bash
+./nginx_to_caddy.sh \
+  --input=./output/nginx-full.conf \
+  --output=./output/Caddyfile.generated \
+  --warnings=./output/conversion-warnings.txt \
+  --tls-mode=cloudflare \
+  --yes
+```
+
+Review warnings:
+
+```bash
+cat ./output/conversion-warnings.txt
+```
+
+If warnings include rewrite/regex/auth directives, expect manual edits.
+
+## 3) Validate generated config
+
+If `caddy` is not installed locally, use Docker:
+
+```bash
+./validate_caddy.sh --config=./output/Caddyfile.generated --docker
+```
+
+If local `caddy` is installed:
+
+```bash
+./validate_caddy.sh --config=./output/Caddyfile.generated
+```
+
+## 4) Canary migration (recommended)
+
+Migrate one low-risk subdomain first:
+1. Copy only one site block from generated Caddyfile to your live Caddy config.
+2. Point only that DNS record to Caddy target.
+3. Verify:
+   - TLS cert valid
+   - page loads
+   - API/websocket calls work
+4. Keep Nginx serving all other subdomains.
+
+## 5) Full migration after canary success
+
+When the canary is stable:
+1. Add remaining site blocks.
+2. Move DNS entries in batches.
+3. Keep Nginx config snapshots for rollback.
+4. Decommission Nginx only after monitoring period.
+
+## 6) Rollback plan
+
+If a site fails after cutover:
+1. Repoint affected DNS entry back to Nginx endpoint.
+2. Restore previous Nginx server block.
+3. Investigate conversion warnings for that block.
+
+## 7) Domain/TLS note for your current setup
+
+You confirmed the domain is `privacyindesign.com`.
+
+If you use `TLS_MODE=cloudflare` with Caddy, ensure:
+- Caddy site labels use `*.privacyindesign.com` or specific subdomains under it.
+- Cloudflare token has DNS edit on the same zone.
+- DNS records point to the Caddy ingress path you intend (direct or via edge proxy).
+
+## 8) Suggested next step for Phase 8
+
+Given your current repo config:
+- keep Phase 8 Caddy focused on `source.privacyindesign.com`
+- migrate broader Nginx estate separately with this toolkit
+
+That keeps Gitea cutover small and lowers blast radius.