diff --git a/SCRATCH/fqdn-migration-api.md b/SCRATCH/fqdn-migration-api.md
new file mode 100644
index 0000000..175bc89
--- /dev/null
+++ b/SCRATCH/fqdn-migration-api.md
@@ -0,0 +1,39 @@
+# API FQDN Migration — Completed Apr 2, 2026
+
+## Summary
+Internal service-to-service traffic in zpac-api now uses `.internal.zlh` FQDNs
+served by Technitium (zlh-dns). All names verified resolving correctly from the API host.
+
+## .env changes
+| Variable | Old value | New value |
+|----------|-----------|-----------|
+| ARTIFACT_BASE_URL | http://10.60.0.17:8080 | http://zlh-artifacts.internal.zlh:8080 |
+| PROM_BASE_URL | http://10.60.0.25:9090/api/v1/query | http://zlh-monitor.internal.zlh:9090/api/v1/query |
+| TECHNITIUM_API_URL | http://10.60.0.14:5380/api | http://zlh-dns.internal.zlh:5380/api |
+| TRAEFIK_HOST | (IP-based) | zlhproxy@zpack-proxy.internal.zlh |
+| PROXY_HOST | (IP-based) | zpack-proxy.internal.zlh |
+| VELOCITY_HOST | (IP-based) | mcproxy@zpack-velocity.internal.zlh |
+| VELOCITY_URL | http://10.70.0.10:8081 | http://zpack-velocity.internal.zlh:8081 |
+
+## Code defaults updated
+- src/utils/catalog.js
+- src/services/technitiumClient.js
+- src/services/proxyClient.js
+- src/services/velocityClient.js
+- src/services/devIdePublisher.js — internal API target → zpack-api.internal.zlh:4000
+
+## CORS allowlist expanded (src/app.js)
+- http://zpack-portal.internal.zlh:3000
+- https://zpack-portal.internal.zlh
+- http://zpack-api.internal.zlh:4000
+
+## Intentionally NOT changed
+- DEV_IDE_HOST_SUFFIX — still zerolaghub.dev (public hosted IDE domain)
+- Public IP and Proxmox public host — left as-is
+- Some IP-based fallbacks kept for resilience on public-edge paths
+- NEXT_PUBLIC_API_BASE_URL in portal — stays as IP (browser can't resolve internal.zlh)
+
+## Verified
+- All .internal.zlh names resolve from API host
+- Velocity registration working via http://zpack-velocity.internal.zlh:8081
+- Syntax checks passed on all touched JS files