# InsForge Deployment - Agent Documentation

## Overview

Deploy frontend applications to InsForge using the `create-deployment` MCP tool. The tool handles uploading source files, building, and deploying automatically.
Source files are uploaded individually through InsForge's deployment proxy; do not zip the project or upload deployment artifacts to storage yourself.
The REST API still supports the legacy zip upload flow for backward compatibility.

## Deploy with MCP Tool

Use the `create-deployment` tool with these parameters:

| Parameter | Required | Description |
|-----------|----------|-------------|
| `sourceDirectory` | Yes | **Absolute path** to source directory (e.g., `/Users/me/project/frontend`). Relative paths do not work. |
| `projectSettings.buildCommand` | No | Build command (default: auto-detected) |
| `projectSettings.outputDirectory` | No | Build output directory (default: auto-detected) |
| `projectSettings.installCommand` | No | Install command (default: `npm install`) |
| `projectSettings.rootDirectory` | No | Root directory within source |
| `envVars` | No | Array of `{key, value}` objects |
| `meta` | No | Custom metadata key-value pairs |

### Example

```json
{
  "sourceDirectory": "/Users/me/project/frontend",
  "projectSettings": {
    "buildCommand": "npm run build",
    "outputDirectory": "dist"
  },
  "envVars": [
    { "key": "VITE_INSFORGE_BASE_URL", "value": "https://your-project.insforge.app" },
    { "key": "VITE_INSFORGE_ANON_KEY", "value": "your-anon-key" }
  ]
}
```

**Important**:
- `sourceDirectory` must be an **absolute path** (relative paths don't work on Windows)
- Pass the source directory, NOT pre-built static files
- Include all required environment variables (e.g., `VITE_*` for Vite apps)

## Check Deployment Status

After creating a deployment, query the status using `run-raw-sql`:

```sql
SELECT id, status, url, created_at
FROM deployments.runs
ORDER BY created_at DESC
LIMIT 1;
```

### Status Values

| Status | Description |
|--------|-------------|
| `WAITING` | Waiting for source zip upload or direct file uploads |
| `UPLOADING` | Uploading files or creating the Vercel deployment |
| `QUEUED` | Queued for build |
| `BUILDING` | Building (typically ~1 min) |
| `READY` | Deployment complete, URL available |
| `ERROR` | Build or deployment failed |
| `CANCELED` | Deployment was cancelled |

### Get Deployment URL

Once status is `READY`, the `url` column contains the live deployment URL.

```sql
SELECT url FROM deployments.runs WHERE id = '<deployment-id>';
```

## SPA Routing (React, Vue, etc.)

Add `vercel.json` to your project root:

```json
{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}
```

## Quick Reference

| Task | Tool | Command |
|------|------|---------|
| Deploy app | `create-deployment` | Provide `sourceDirectory` and `envVars` |
| Check status | `run-raw-sql` | `SELECT status FROM deployments.runs WHERE id = '...'` |
| List deployments | `run-raw-sql` | `SELECT * FROM deployments.runs ORDER BY created_at DESC` |
