feat: One-Click Deploy with Auto-Provisioning — zero to live dashboard in 30 seconds

[alohays]

Problem

monitor-forge's deploy experience has significant friction compared to modern template projects:

1. Manual token management: forge deploy --token <token> --prod requires users to manually obtain and pass Vercel tokens
2. No one-click deploy: Unlike vercel-labs/coding-agent-template which has a Deploy button that auto-provisions PostgreSQL (Neon), monitor-forge has no equivalent
3. Incomplete env var documentation: .env.example only documents GROQ_API_KEY, but the actual requirements depend on enabled features (AI provider keys, Upstash Redis for caching, etc.)
4. No service auto-provisioning: Users must manually set up Upstash Redis for caching, manually configure CORS domains, and manually manage all environment variables
5. No preset selection during deploy: New users must clone → configure locally → deploy, instead of choosing a preset at deploy time
6. Build command hardcoded in vercel.json: "buildCommand": "npx forge build --skip-vite && npx vite build" — correct but opaque to users who haven't read the docs

The gap: vercel-labs/coding-agent-template achieves "click Deploy → fill env vars → live app" in under a minute. monitor-forge requires cloning, installing, running CLI commands, manually creating env files, and then deploying. For a project whose value proposition is "build your own dashboard easily," this friction is a serious adoption blocker.

Solution

1. Vercel Deploy Button

Add a one-click Deploy button to README that pre-configures everything:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Falohays%2Fmonitor-forge&env=GROQ_API_KEY&envDescription=API%20keys%20for%20AI%20analysis%20and%20caching&envLink=https%3A%2F%2Fgithub.com%2Falohays%2Fmonitor-forge%23environment-variables&project-name=my-monitor&repository-name=my-monitor-forge)

What happens when clicked:

1. User forks the repo to their GitHub account
2. Vercel prompts for required environment variables (with descriptions and links)
3. Project builds and deploys automatically
4. User gets a live dashboard URL in ~60 seconds

2. Environment Variable Configuration

Create comprehensive env var metadata for the deploy flow:

Required (always):

Variable	Description	Where to get it
GROQ_API_KEY	AI analysis (free tier available)	console.groq.com

Optional (feature-dependent):

Variable	Feature	Description
OPENROUTER_API_KEY	AI fallback	Secondary AI provider
UPSTASH_REDIS_REST_URL	Caching	Redis cache for API responses
UPSTASH_REDIS_REST_TOKEN	Caching	Redis authentication token

Update forge env check to show this same table with status indicators.

3. Upstash Redis Auto-Provisioning via Vercel Integration

Leverage Vercel's Upstash Integration for automatic Redis provisioning:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=...&integration-ids=oac_V3R1GIpkoJorr6fqyiwdhl17)

When integration-ids includes Upstash's ID:

• Redis instance auto-created during deploy
• UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN auto-injected
• Zero manual Redis setup required

4. Preset Selection in Deploy Flow

Support preset selection via URL query parameter:

https://vercel.com/new/clone?...&env=PRESET&envDescription=Choose+a+preset

Or better — add a post-deploy setup step:

// api/setup/v1/route.ts (Edge Function)
// Called after first deploy, presents preset selector
// Writes selected preset to config and triggers rebuild

Alternative approach: Include all presets in the repo and let users switch via:

npx forge preset apply tech-full --format json

Document this as a "Quick Start" step post-deploy.

5. Post-Deploy Health Check

Add a health endpoint that forge doctor can verify remotely:

// api/health/v1/route.ts
export async function GET() {
  return Response.json({
    status: 'ok',
    version: process.env.npm_package_version,
    preset: config.monitor.name,
    sources: config.sources.length,
    panels: config.panels.length,
    cache: !!process.env.UPSTASH_REDIS_REST_URL,
    ai: !!process.env.GROQ_API_KEY,
  });
}

# Verify remote deployment
forge doctor --remote https://my-monitor.vercel.app
# ✓ Health endpoint responding
# ✓ 5 sources configured
# ✓ 4 panels active
# ✓ Redis cache connected
# ✓ AI provider configured (Groq)

6. Documentation: "Deploy in 30 Seconds" Section

Add to README:

## Quick Start

### Option A: One-Click Deploy (Recommended)
1. Click the Deploy button above
2. Enter your Groq API key ([get one free](https://console.groq.com))
3. Done! Your dashboard is live.

### Option B: Local Development
1. `npx forge setup` (interactive wizard, see #28)
2. `npm run dev`
3. `npm run deploy`

Implementation Notes

Files to modify:

• README.md — add Deploy button and Quick Start section
• forge/src/commands/deploy.ts — improve deploy flow, add --remote flag for doctor
• .env.example — comprehensive env var documentation with descriptions
• vercel.json — ensure build command works for fresh clones

Files to create:

• api/health/v1/route.ts — health check endpoint
• docs/deploy.md — detailed deployment guide (optional, can be in README)

Key decisions:

• Deploy button URL parameters must be carefully crafted and tested
• Upstash integration ID needs to be verified (oac_V3R1GIpkoJorr6fqyiwdhl17 is their published ID)
• Post-deploy preset selection could be Phase 2 (start with default preset)

Backward compatibility:

• Zero breaking changes — existing manual deploy workflow continues to work
• Deploy button is additive (README change only)
• Health endpoint is a new Edge Function (no existing code modified)