@arthai/agents 1.0.0

package/skills/custom-domain/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: custom-domain
+description: "Set up, diagnose, or fix custom domain configuration (DNS + app platform + auth + CORS). Commands: setup, check, fix"
+user-invocable: true
+arguments: "command"
+---
+
+# Custom Domain Skill
+
+Manage custom domain configuration across DNS provider, app platform, auth provider, and CORS.
+
+## Argument Parsing
+
+- `command`: Optional. One of: `setup`, `check`, `fix`. Defaults to `check` if omitted.
+
+## Discovery Phase (All Commands)
+
+Before any action, discover the project's domain stack by reading config and env vars:
+
+```
+1. DNS Provider — Check if Cloudflare is in use:
+   curl -sI https://<domain> | grep -i "server: cloudflare"
+   dig <domain> CNAME +short
+
+2. App Platform — Check Railway services:
+   railway status
+   railway domain (on frontend service)
+
+3. Auth Provider — Detect from frontend code:
+   grep -r "STYTCH\|AUTH0\|CLERK\|SUPABASE_AUTH\|FIREBASE_AUTH" frontend/.env* frontend/src/lib/
+
+4. Backend CORS — Check current config:
+   railway variables --kv --service backend | grep CORS
+   railway variables --kv --service backend | grep FRONTEND_URL
+
+5. Custom domain already set? —
+   curl -sI https://<domain> | head -10
+```
+
+Store discovered values for use in subsequent steps.
+
+---
+
+## `/custom-domain setup`
+
+Full end-to-end setup of a new custom domain.
+
+### Step 1: Add Custom Domain in Railway
+
+```bash
+railway service frontend
+railway domain <your-domain.com> --json
+```
+
+The JSON response contains `requiredValue` — this is the CNAME target for DNS. It is NOT the same as the public Railway URL. Railway assigns a separate routing hostname for custom domains.
+
+### Step 2: Configure DNS
+
+**If Cloudflare (recommended):**
+
+Check if Railway offers one-click Cloudflare integration in the dashboard:
+- Railway dashboard -> Frontend service -> Settings -> Custom Domain -> "Connect to Cloudflare"
+- This auto-configures CNAME + TXT verification record + proxy settings
+- Click **Authorize** when prompted
+
+**If manual DNS setup:**
+
+| Field | Value |
+|-------|-------|
+| Type | `CNAME` |
+| Name | `@` (root) or subdomain |
+| Target | `requiredValue` from Step 1 |
+| Proxy | DNS only (grey cloud) for manual; Proxied OK with Railway's Cloudflare integration |
+
+**If non-Cloudflare DNS provider:**
+- Add CNAME record pointing to the `requiredValue`
+- Add any TXT records Railway requires for verification
+- SSL will be provisioned by Railway via Let's Encrypt (may take 2-10 min)
+
+### Step 3: Update Backend CORS + FRONTEND_URL
+
+```bash
+railway service backend
+railway variables set 'CORS_ORIGINS=["https://<new-domain>","https://<existing-railway-frontend-url>"]'
+railway variables set 'FRONTEND_URL=https://<new-domain>'
+```
+
+**CRITICAL — JSON quoting for CORS_ORIGINS:**
+- Value MUST be valid JSON: `["https://domain1","https://domain2"]`
+- Use `railway variables set` CLI directly (NOT the MCP set-variables tool — it strips inner quotes)
+- Verify after setting: `railway variables --kv | grep CORS`
+- If inner quotes are missing, Pydantic (or similar config parser) fails to parse -> app crashes on deploy
+- Keep the old Railway URL in the array so both domains work simultaneously
+
+This triggers a backend redeploy. Wait for it to go green.
+
+### Step 4: Configure Auth Provider
+
+**If Stytch:**
+In Stytch Dashboard -> Live project:
+1. **Frontend SDKs -> Authorized environments** -> Add: `<your-domain.com>`
+2. **Redirect URLs** -> Add:
+   - `https://<your-domain.com>/authenticate` (type: Login)
+   - `https://<your-domain.com>/authenticate` (type: Sign-up)
+
+**If Auth0:** Add `https://<your-domain.com>` to Allowed Callback URLs, Allowed Logout URLs, Allowed Web Origins.
+
+**If Clerk:** Add domain to Clerk Dashboard -> Paths -> Allowed origins.
+
+**If Supabase Auth:** Add redirect URL in Supabase Dashboard -> Auth -> URL Configuration.
+
+No code changes needed for any of these — auth SDKs auto-detect the current domain.
+
+### Step 5: Verify
+
+```bash
+# DNS resolution
+nslookup <your-domain.com>
+
+# HTTPS + SSL working
+curl -sI https://<your-domain.com> | head -10
+# Should return HTTP/2 200
+
+# Backend CORS working (after deploy completes)
+curl -sI -H "Origin: https://<your-domain.com>" https://<backend-url>/health | grep -i "access-control"
+
+# Auth flow — test in browser
+# Navigate to https://<your-domain.com>/login and complete login
+```
+
+---
+
+## `/custom-domain check` (default)
+
+Diagnose the current domain setup. Run all checks and report pass/fail.
+
+```
+Domain Health Check:
+  DNS Resolution:     pass/fail (nslookup + CNAME target)
+  SSL Certificate:    pass/fail (curl -sI, check for valid cert)
+  Frontend Serving:   pass/fail (HTTP 200 from custom domain)
+  Backend CORS:       pass/fail (CORS_ORIGINS includes custom domain)
+  FRONTEND_URL:       pass/fail (points to custom domain)
+  Auth Provider:      pass/fail (domain in authorized list — manual check, remind user)
+  Railway Domain:     pass/fail (old .up.railway.app still works)
+```
+
+### Check Commands
+
+```bash
+# 1. DNS
+dig <domain> CNAME +short
+nslookup <domain>
+
+# 2. SSL
+curl -svI https://<domain> 2>&1 | grep -E "subject:|subjectAltName|SSL"
+
+# 3. Frontend
+curl -sI https://<domain> | head -5
+
+# 4. CORS
+railway service backend
+railway variables --kv | grep CORS_ORIGINS
+# Verify the custom domain is in the JSON array WITH quotes
+
+# 5. FRONTEND_URL
+railway variables --kv | grep FRONTEND_URL
+
+# 6. Railway URL still works
+curl -sI https://<railway-frontend-url> | head -3
+```
+
+---
+
+## `/custom-domain fix`
+
+Fix common domain issues based on symptoms.
+
+### Issue: CORS blocking (dashboard spinning after login)
+
+**Symptom:** Console error: `Access to fetch blocked by CORS policy: No 'Access-Control-Allow-Origin' header`
+
+**Fix:**
+```bash
+railway service backend
+# Check current value
+railway variables --kv | grep CORS_ORIGINS
+# Fix — ensure proper JSON with inner quotes
+railway variables set 'CORS_ORIGINS=["https://<custom-domain>","https://<railway-frontend-url>"]'
+# Verify
+railway variables --kv | grep CORS_ORIGINS
+# Wait for redeploy
+```
+
+### Issue: Backend crash after CORS change
+
+**Symptom:** Config parser error like `SettingsError: error parsing value for field "CORS_ORIGINS"`
+
+**Cause:** Inner quotes stripped from JSON array. MCP set-variables tool or Railway dashboard may mangle JSON.
+
+**Fix:** Use `railway variables set` CLI directly with single-quoted value:
+```bash
+railway variables set 'CORS_ORIGINS=["https://domain1","https://domain2"]'
+```
+
+### Issue: SSL certificate mismatch
+
+**Symptom:** `subjectAltName does not match host name`
+
+**Cause:** Railway hasn't provisioned SSL cert yet (takes 2-10 min), or Cloudflare proxy is off.
+
+**Fix:**
+- Wait 10 minutes and retry
+- If using Cloudflare, enable proxy (orange cloud) — Cloudflare provides instant SSL
+- Check Railway dashboard for domain verification status
+
+### Issue: Auth session refresh failing
+
+**Symptom:** Auth SDK reports session refresh failed, signs user out on the new domain.
+
+**Cause:** Custom domain not in auth provider's authorized environments/origins list.
+
+**Fix:** Add the domain in your auth provider's dashboard (see Step 4 of setup).
+
+### Issue: Cloudflare Insights CSP violation
+
+**Symptom:** `static.cloudflareinsights.com/beacon.min.js violates Content Security Policy`
+
+**Cause:** Cloudflare proxy injects analytics script; CSP doesn't allow it.
+
+**Fix:** Add to `script-src` in your security headers config:
+```
+https://static.cloudflareinsights.com
+```
+Non-blocking — only affects Cloudflare analytics, not app functionality.
+
+---
+
+## What Does NOT Need to Change
+
+- **Frontend env vars** — API URL stays as backend Railway URL (frontend talks to backend directly)
+- **Agent/worker services** — no changes needed
+- **Backend code** — CORS is configured via env vars, not hardcoded
+- **Old Railway URL** — continues working alongside custom domain (both serve the same app)
+
+## Project-Specific Reference
+
+Add a section at the bottom of your project's copy of this skill with your actual values:
+
+```markdown
+## Project Reference Values
+
+| Item | Value |
+|------|-------|
+| Custom domain | `your-domain.com` |
+| CNAME target | `xxx.up.railway.app` |
+| Frontend Railway URL | `frontend-production-xxx.up.railway.app` |
+| Backend Railway URL | `backend-production-xxx.up.railway.app` |
+| Auth provider | Stytch / Auth0 / Clerk / etc. |
+| DNS provider | Cloudflare / etc. |
+```