chore(deploy): pre-deploy audit + fix requirements.txt boot-blocker

.env.example

@@ -0,0 +1,51 @@
+# kratos-clone — environment variables reference
+#
+# Copy this file to `.env` (gitignored) for local dev, or set the values
+# in the Render/Railway dashboard for production.
+#
+# Lifecycle column (right of each var):
+#   [boot]      — read once at process start. Missing/invalid → loud failure.
+#   [request]   — read per request or per capture. Missing → silent 5xx
+#                 or fallback to default.
+#   [test-only] — only consumed by `tests/` / CLI; not needed for the
+#                 Flask service.
+
+# ── Required for /api/personalize/* ────────────────────────────────────
+# Without this, /api/personalize/structure and /api/personalize/run will
+# return 5xx on first call (lazy-loaded by the OpenAI SDK at request
+# time, not at boot). /download (legacy Flask UI) works without it.
+OPENAI_API_KEY=                          # [request] no default; required for personalize endpoints
+
+# ── Logging (kratos_clone/_logging.py) ─────────────────────────────────
+LOG_FORMAT=console                       # [boot] console | json. Use json in prod.
+LOG_LEVEL=INFO                           # [boot] DEBUG | INFO | WARNING | ERROR | CRITICAL
+
+# ── HTTP / proxy (app.py) ──────────────────────────────────────────────
+PORT=8080                                # [boot] Render/Railway override automatically
+TRUST_PROXY=0                            # [boot] set 1 only behind a proxy that strips client X-Forwarded-For
+RATE_LIMIT_STORAGE_URI=memory://         # [boot] use redis://... if running with --workers >1
+
+# ── Rate limits (app.py decorators) ────────────────────────────────────
+CLIENT_ERRORS_RATE_LIMIT=60 per minute   # [boot]
+PERSONALIZE_STRUCTURE_RATE_LIMIT=5 per minute    # [boot]
+PERSONALIZE_RUN_RATE_LIMIT=2 per minute  # [boot]
+
+# ── Capture knobs (kratos_clone/capture.py, CLI + downloader) ──────────
+KCD_VIEWPORT_WIDTH=1920                  # [request]
+KCD_VIEWPORT_HEIGHT=1080                 # [request]
+KCD_USER_AGENT=                          # [request] default = Chrome 120 macOS
+KCD_NAV_TIMEOUT=90000                    # [request] ms
+KCD_DOM_STABLE_MS=1500                   # [request] ms
+KCD_NETIDLE_BUFFER=5000                  # [request] ms
+KCD_SCROLL_PASSES=3                      # [request] 1–3
+KCD_HEADED=false                         # [request] true to run browser headed
+KCD_CAPTURE_COMPUTED_STYLES=true         # [request]
+KCD_IO_POLYFILL=true                     # [request] IntersectionObserver pre-fire patch
+KCD_SHADOW_WALKER=true                   # [request] Shadow DOM serializer patch
+KCD_BLOCK_ANALYTICS=true                 # [request] block GA / Segment / etc.
+KCD_MAX_SCROLL_S=120                     # [request] hard cap on scroll wall-clock
+KCD_MAX_TOTAL_MB=200                     # [request] hard cap on total asset bytes
+KCD_MAX_ASSETS=500                       # [request] hard cap on asset count
+
+# ── Test-only ──────────────────────────────────────────────────────────
+RUN_OPENAI_LIVE=                         # [test-only] set 1 + provide OPENAI_API_KEY to run tests/integration/. Spends ~$0.105 per run.