AGS — Deployment

Deployment CLAUDE.md

Branch strategy

feature branch  →  PR into staging  →  validate  →  PR staging into main
                        ↓                                     ↓
                  Railway staging                      Railway production

Never commit .env or *.local.*. Secrets are Railway environment variables. GitHub Actions deploys both services automatically on push.

Required environment variables

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`JWT_SECRET`	Participant JWT signing key (HS256)
`RESEARCHER_JWT_SECRET`	Researcher JWT. Must be different from JWT_SECRET.
`PHONE_HMAC_SECRET`	HMAC-SHA256 key for phone tokens. Must differ from JWT_SECRET — JWT rotation should not invalidate phone reauth.
`MISTRAL_API_KEY`	Required for Level 3 (walkthrough) interventions and explicit Level 3 help. Without this key, all L3 responses fall back to scripted content only. L1 and L2 scripted help is unaffected.
`DASHBOARD_RESEARCHER_EMAIL`	Default researcher account seeded on first deploy.
`DASHBOARD_RESEARCHER_PASSWORD`	Default researcher account password.

Migrations & common commands

# Apply all pending migrations (runs automatically on Railway deploy)
alembic upgrade head

# Generate a new migration after model changes
alembic revision --autogenerate -m "description"

# Roll back one migration
alembic downgrade -1

# Check current migration head
.venv/bin/alembic heads

# Backend dev server
uvicorn src.main:app --reload --port 8000

# Frontend dev server (proxies /v1/* to :8000)
cd dashboard && npm run dev

# Railway logs
railway service AGS && railway logs

Keeping this documentation current

When you change something fundamental, update the matching section.

Pipeline formula weights (src/config.py lines 15–25) → update Readiness Model weight bars and formula text
Readiness band thresholds (READINESS_HIGH/MODERATE/LOW) → update state band table
Cooldown values (COOLDOWN_*_S) → update cooldown table
Governance gate order or rule list → update Governance System flowchart and rule table
_ALWAYS_ADAPTIVE_BYPASS set → update always_adaptive bypass note and conditions table
Adaptation levels or content resolution order → update Adaptation section
API endpoints added or removed → update API Reference tables
Hard Rules change → update Privacy & Ethics table

Each section header has a source file tag showing which file it maps to. The live config fetch (for researchers logged into the dashboard) will automatically flag any threshold values that differ from what's documented here.