fix(GEN-3647): restore api.gen.pro docs routing after CloudFront exit

[mavxdegods]

Incident

https://api.gen.pro docs site returns 404 on every path (/, /llms.txt, /llms-full.txt, /openapi.yaml, /guides/*, /reference/*, /cards/*). Reported as "the site is down."

The API itself is healthy — /up=200, /v1/templates/projects=200, /v1/agents=401. Only the docs website is down.

Root cause

api.gen.pro is a dual-purpose host:

• /v1, /up, … → Rails (gen-backend-v2, now Hetzner 5.161.246.2)
• everything else → Astro Starlight docs on GitHub Pages (poweredbygen.github.io/api-docs/)

A CloudFront distribution used to split these paths and rewrite the Pages origin path to /api-docs. The CloudFront exit (Hetzner migration, GEN-3617 / GEN-3620) removed CloudFront and pointed api.gen.pro entirely at Rails → Rails has no docs routes → every docs path 404s. Docs content is intact at the Pages origin (verified 200).

Compounding fragility: astro.config has site: 'https://api.gen.pro' with no base: and no CNAME, so published assets are root-relative (/_astro/*) but Pages serves them under /api-docs/_astro/* — only ever worked because the old edge rewrote the origin path.

Fix (this PR)

Edge-routing artifacts — no redeploy of the docs needed:

• cloudflare/api-gen-pro-router.worker.js — Worker bound to api.gen.pro/*: API prefixes → Rails origin, all else → GitHub Pages (/api-docs prepend + Pages-redirect rewrite). Recommended.
• cloudflare/DEPLOY.md — Worker deploy + verify steps.
• cloudflare/DEPLOY-no-worker.md — native Origin Rules + URL Rewrite alternative (no code).

⚠️ Applying the fix is a Cloudflare dashboard change (deploy Worker, bind api.gen.pro/* route, add unproxied origin-api.gen.pro → 5.161.246.2). This PR only lands the artifacts + runbook.

Verify after deploy

for p in / /llms.txt /llms-full.txt /openapi.yaml /reference/agents/; do curl -s -o /dev/null -w "$p -> %{http_code}\n" "https://api.gen.pro$p"; done   # all 200
curl -s -o /dev/null -w "/up -> %{http_code}\n" https://api.gen.pro/up                  # 200
curl -s -o /dev/null -w "/v1 -> %{http_code}\n" https://api.gen.pro/v1/templates/projects  # 200

Monitoring (self-healing rule)

Added api-docs-route-monitor.timer on Hetzner box-trendpulse (5-min synthetic probe; alerts if docs paths ≠ 200 while /up healthy). checked:no_safe_auto_fix_mapped.

Permanent hardening (follow-up)

Move docs to docs.gen.pro (Pages custom-domain CNAME) or set Astro base: '/api-docs'.

Tracking: GEN-3647 · Related: GEN-3617, GEN-3620, GEN-2768

🤖 Generated with Claude Code