Add Agent Relay Cloud onboarding design document

.claude/agents/lead.md

@@ -27,6 +27,20 @@ You are a Lead agent - a coordinator and decision-maker, NOT an implementer. You
 - Update issue status immediately when work starts/completes
 - Keep a running mental model of who's doing what
 
+### 4. Broadcast Status via [[SUMMARY]] Blocks
+**IMPORTANT:** Always emit [[SUMMARY]] blocks to communicate your current state. This is the preferred agent-to-agent communication method and enables the dashboard to display real-time task info.
+
+Emit a [[SUMMARY]] block:
+- When you start working on a new task
+- After delegating work to agents
+- When status changes significantly
+- At regular intervals during long sessions
+
+Format:
+```
+[[SUMMARY]]{"currentTask":"agent-relay-XXX: Brief description","completedTasks":["agent-relay-YYY"],"context":"Who's working on what"}[[/SUMMARY]]
+```
+
 ## Role Assignments
 
 When delegating, match tasks to roles:
@@ -171,14 +185,29 @@ Periodically broadcast status:
 **Next:** [What's coming next]>>>
 ```
 
-## Session Summary Pattern
+## Session Summary Pattern (REQUIRED)
+
+**You MUST emit [[SUMMARY]] blocks regularly.** This is how other agents and the dashboard know what you're working on.
 
-Use [[SUMMARY]] blocks to track your state:
+### When to Emit
+1. **After receiving a task** - Show what you're now coordinating
+2. **After delegating** - Show updated team assignments
+3. **After task completion** - Update completedTasks array
+4. **Every 2-3 interactions** - Keep status fresh
 
+### Format
 ```
-[[SUMMARY]]{"currentTask":"Coordinating team on feature X","context":"Implementer working on backend, Designer on UI. 3 issues in progress."}[[/SUMMARY]]
+[[SUMMARY]]{"currentTask":"agent-relay-315: Coordinating LogViewer fix","completedTasks":["agent-relay-310","agent-relay-312"],"context":"Implementer on 315, Frontend on 316. Awaiting ETAs.","decisions":["Prioritized P1 bugs first"]}[[/SUMMARY]]
 ```
 
+### Dashboard Integration
+The dashboard parses these blocks to display:
+- Your current task next to your name in the sidebar
+- Real-time status of what each agent is doing
+- Historical context of completed work
+
+**If you don't emit [[SUMMARY]] blocks, the dashboard won't show your current task.**
+
 ## Key Metrics
 
 Track these throughout a session:

.eslintrc.cjs

@@ -28,5 +28,5 @@ module.exports = {
       },
     ],
   },
-  ignorePatterns: ['dist/**', 'node_modules/**', 'coverage/**'],
+  ignorePatterns: ['dist/**', 'node_modules/**', 'coverage/**', '**/out/**'],
 };

.github/workflows/docker.yml

@@ -0,0 +1,69 @@
+name: Docker
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Image tag (default: latest)'
+        required: false
+        default: 'latest'
+
+env:
+  REGISTRY: ghcr.io
+  ORG: agentworkforce
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - image: agent-relay
+            dockerfile: Dockerfile
+            context: .
+          - image: agent-relay-workspace
+            dockerfile: deploy/workspace/Dockerfile
+            context: deploy/workspace
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.ORG }}/${{ matrix.image }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: ${{ matrix.context }}
+          file: ${{ matrix.dockerfile }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64

Dockerfile

@@ -0,0 +1,62 @@
+# Agent Relay Cloud - Control Plane
+# Runs the Express API server with PostgreSQL/Redis connections
+
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy package files
+COPY package*.json ./
+COPY src/dashboard/package*.json ./src/dashboard/
+
+# Install dependencies
+RUN npm ci --include=dev
+
+# Copy source
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+# Build dashboard
+RUN cd src/dashboard && npm ci && npm run build
+
+# Production image
+FROM node:20-slim AS runner
+
+WORKDIR /app
+
+# Install runtime dependencies only
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy built artifacts
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/src/dashboard/out ./src/dashboard/out
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package*.json ./
+
+# Create non-root user
+RUN useradd -m -u 1001 agentrelay
+USER agentrelay
+
+# Environment
+ENV NODE_ENV=production
+ENV PORT=3000
+
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
+
+# Start cloud server
+CMD ["node", "dist/cloud/index.js"]

deploy/.env.cloud.example

@@ -0,0 +1,83 @@
+# Agent Relay Cloud - Production Environment Configuration
+# Copy to .env.cloud and fill in your values
+
+# =============================================================================
+# Domain Configuration
+# =============================================================================
+# Main domains for your deployment
+LANDING_URL=https://agent-relay.com
+APP_URL=https://app.agent-relay.com
+API_URL=https://api.agent-relay.com
+WORKSPACE_DOMAIN=ws.agent-relay.com
+
+# Public URL (used for OAuth callbacks, etc.)
+PUBLIC_URL=https://api.agent-relay.com
+
+# =============================================================================
+# Server Configuration
+# =============================================================================
+PORT=3000
+NODE_ENV=production
+SESSION_SECRET=generate-a-32-byte-random-string-here
+
+# =============================================================================
+# Database (PostgreSQL)
+# =============================================================================
+# Railway provides this automatically when you add PostgreSQL
+DATABASE_URL=postgresql://user:password@host:5432/agent_relay
+
+# =============================================================================
+# Redis (Sessions & Caching)
+# =============================================================================
+# Railway provides this automatically when you add Redis
+REDIS_URL=redis://localhost:6379
+
+# =============================================================================
+# GitHub OAuth
+# =============================================================================
+# Create a GitHub OAuth App: https://github.com/settings/applications/new
+# Homepage URL: https://agent-relay.com
+# Callback URL: https://api.agent-relay.com/api/auth/github/callback
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# =============================================================================
+# Compute Provider (for user workspaces)
+# =============================================================================
+# Options: fly, railway, docker
+COMPUTE_PROVIDER=fly
+
+# Fly.io Configuration (recommended for workspaces)
+# Get token: fly auth token
+FLY_API_TOKEN=your-fly-api-token
+FLY_ORG=personal
+FLY_REGION=sjc
+
+# Custom domain for workspaces (CNAME *.ws.agent-relay.com to fly.dev)
+FLY_WORKSPACE_DOMAIN=ws.agent-relay.com
+
+# =============================================================================
+# Stripe Billing
+# =============================================================================
+# Get keys from: https://dashboard.stripe.com/apikeys
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_PUBLISHABLE_KEY=pk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# Price IDs from Stripe Products
+STRIPE_PRICE_PRO_MONTHLY=price_...
+STRIPE_PRICE_PRO_YEARLY=price_...
+STRIPE_PRICE_TEAM_MONTHLY=price_...
+STRIPE_PRICE_TEAM_YEARLY=price_...
+
+# =============================================================================
+# Encryption (for credential vault)
+# =============================================================================
+# Generate with: openssl rand -hex 32
+VAULT_ENCRYPTION_KEY=generate-a-64-character-hex-string
+
+# =============================================================================
+# Optional: Monitoring & Logging
+# =============================================================================
+# SENTRY_DSN=https://xxx@sentry.io/xxx
+# LOG_LEVEL=info

deploy/init-db.sql

@@ -0,0 +1,5 @@
+-- Agent Relay Cloud - Database bootstrap
+-- Deprecated: use migrations in src/cloud/db/migrations/0001_initial.sql
+-- This file is kept as a convenience wrapper for local psql usage.
+
+\\i ../src/cloud/db/migrations/0001_initial.sql

deploy/scripts/setup-fly-workspaces.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Setup Fly.io for Agent Relay Workspaces
+# Run this from the project root
+
+set -e
+
+echo "=== Agent Relay Cloud - Fly.io Workspace Setup ==="
+echo ""
+
+# Check for fly CLI
+if ! command -v fly &> /dev/null; then
+    echo "Error: Fly CLI not found. Install it with:"
+    echo "  curl -L https://fly.io/install.sh | sh"
+    exit 1
+fi
+
+# Check if logged in
+if ! fly auth whoami &> /dev/null; then
+    echo "Please log in to Fly.io first:"
+    fly auth login
+fi
+
+# Get org
+FLY_ORG=${FLY_ORG:-personal}
+echo "Using Fly.io org: $FLY_ORG"
+
+echo ""
+echo "=== Building Workspace Image ==="
+echo ""
+
+# Build and push the workspace image
+cd deploy/workspace
+
+echo "Building workspace Docker image..."
+docker build -t ghcr.io/khaliqgant/agent-relay-workspace:latest .
+
+echo ""
+echo "Pushing to GitHub Container Registry..."
+echo "(Make sure you're logged in: docker login ghcr.io)"
+docker push ghcr.io/khaliqgant/agent-relay-workspace:latest
+
+cd ../..
+
+echo ""
+echo "=== Get Your API Token ==="
+echo ""
+echo "Run this to get your Fly.io API token:"
+echo "  fly auth token"
+echo ""
+echo "Add it to your Railway environment:"
+echo "  FLY_API_TOKEN=<token>"
+echo "  FLY_ORG=$FLY_ORG"
+echo "  COMPUTE_PROVIDER=fly"
+echo ""
+
+echo "=== Custom Domain Setup ==="
+echo ""
+echo "To use custom workspace domains (e.g., abc123.ws.agent-relay.com):"
+echo ""
+echo "1. Add a wildcard CNAME record in your DNS:"
+echo "   *.ws.agent-relay.com  CNAME  fly.dev"
+echo ""
+echo "2. Set the domain in Railway:"
+echo "   FLY_WORKSPACE_DOMAIN=ws.agent-relay.com"
+echo ""
+echo "3. Each workspace will be accessible at:"
+echo "   https://{workspace-id}.ws.agent-relay.com"
+echo ""
+echo "Setup complete!"