CrewForm · vincentgrobler · Feb 25, 2026 · Feb 25, 2026
diff --git a/README.md b/README.md
@@ -21,6 +21,7 @@
 - [Why CrewForm?](#why-crewform)
 - [Key Features](#key-features)
 - [Quick Start](#quick-start)
+- [Documentation](#documentation)
 - [Architecture](#architecture)
 - [Tech Stack](#tech-stack)
 - [How CrewForm Compares](#how-crewform-compares)
@@ -71,7 +72,17 @@ cp .env.example .env.local
 npm run dev
 ```
 
-> **Self-hosting?** See our [Docker deployment guide](https://docs.crewform.tech/self-hosting) for production setup.
+> **Self-hosting?** See the [Docker deployment guide](docs/self-hosting.md) for production setup.
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Quick Start](docs/quickstart.md) | Get running in under 5 minutes |
+| [Agents Guide](docs/agents.md) | Models, system prompts, and agent lifecycle |
+| [Pipeline Teams](docs/pipeline-teams.md) | Multi-agent workflows and handoffs |
+| [API Reference](docs/api-reference.md) | REST API endpoints and authentication |
+| [Self-Hosting](docs/self-hosting.md) | Docker Compose production deployment |
 
 ## Architecture
 

diff --git a/docs/agents.md b/docs/agents.md
@@ -0,0 +1,109 @@
+# Agents Guide
+
+Agents are the core building blocks of CrewForm. Each agent is an AI worker configured with a specific model, system prompt, and capabilities.
+
+## Creating an Agent
+
+Navigate to **Agents → New Agent** or use the `+` button.
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| **Name** | Human-readable identifier (e.g., "Code Reviewer") |
+| **Model** | LLM model to use (see [Supported Models](#supported-models)) |
+| **System Prompt** | Instructions that define the agent's behavior |
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| **Description** | What the agent does (shown in marketplace) |
+| **Temperature** | Creativity level (0.0 = deterministic, 1.0 = creative) |
+| **Max Tokens** | Maximum response length |
+| **Tags** | Categorization for search and marketplace |
+
+## Supported Models
+
+CrewForm supports three LLM providers. You must add your API key in **Settings → API Keys** before using a provider.
+
+### Anthropic (Claude)
+
+| Model | Best For |
+|-------|----------|
+| `claude-sonnet-4-20250514` | General-purpose, balanced cost/quality |
+| `claude-3-5-haiku-20241022` | Fast, cost-effective tasks |
+| `claude-3-opus-20240229` | Complex reasoning, analysis |
+
+### Google (Gemini)
+
+| Model | Best For |
+|-------|----------|
+| `gemini-2.0-flash` | Fast, multimodal tasks |
+| `gemini-1.5-pro` | Long-context, complex tasks |
+
+### OpenAI (GPT)
+
+| Model | Best For |
+|-------|----------|
+| `gpt-4o` | General-purpose, fast |
+| `gpt-4-turbo` | Complex reasoning |
+| `gpt-3.5-turbo` | Simple, high-volume tasks |
+
+## Writing System Prompts
+
+The system prompt defines your agent's personality, expertise, and output format. Tips:
+
+### Be Specific
+
+```
+❌ "You are a helpful assistant."
+✅ "You are a senior code reviewer specializing in TypeScript and React.
+    You review code for bugs, performance issues, and best practices.
+    Output your review as a numbered list with severity (HIGH/MEDIUM/LOW)."
+```
+
+### Define Output Format
+
+```
+You must respond in the following JSON format:
+{
+  "summary": "one-line summary",
+  "findings": [{ "severity": "HIGH|MEDIUM|LOW", "description": "..." }],
+  "recommendation": "overall recommendation"
+}
+```
+
+### Set Boundaries
+
+```
+You ONLY review code. If asked to write new code, respond with:
+"I'm configured as a reviewer. Please create a separate coding agent."
+```
+
+## Agent Lifecycle
+
+```
+Created → Idle → Running (task assigned) → Idle
+                    ↓
+               Failed (error)
+```
+
+- **Idle**: Ready to accept tasks
+- **Running**: Actively processing a task
+- **Failed**: Task errored — check the task detail for the error message
+
+## Using Agents in Teams
+
+Agents become more powerful when combined into teams. See the [Pipeline Teams Guide](./pipeline-teams.md) for multi-agent workflows.
+
+## API Key Security
+
+All API keys are encrypted with **AES-256-GCM** before storage. Keys are:
+
+- Encrypted client-side before being sent to the database
+- Never stored in plaintext
+- Only decrypted by the task runner at execution time
+- Scoped to your workspace via Row-Level Security
+
+See [Settings → API Keys] in the app to manage your provider keys.
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -0,0 +1,250 @@
+# REST API Reference
+
+CrewForm exposes a REST API via Supabase for programmatic access to your workspace. Authenticate using API keys created in **Settings → API Keys**.
+
+## Authentication
+
+All API requests require a REST API key in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer crfm_your_api_key" \
+     -H "Content-Type: application/json" \
+     https://your-project.supabase.co/rest/v1/agents
+```
+
+### Creating API Keys
+
+1. Go to **Settings → API Keys**
+2. Click **Generate Key**
+3. Copy the key — it's only shown once
+4. The key is hashed (SHA-256) before storage for security
+
+## Endpoints
+
+All endpoints are accessed via the Supabase REST API at:
+
+```
+https://<your-project>.supabase.co/rest/v1/<table>
+```
+
+You also need the `apikey` header with your Supabase anon key:
+
+```bash
+curl -H "Authorization: Bearer crfm_your_api_key" \
+     -H "apikey: your-supabase-anon-key" \
+     https://your-project.supabase.co/rest/v1/agents
+```
+
+---
+
+## Agents
+
+### List Agents
+
+```http
+GET /rest/v1/agents?select=*
+```
+
+**Response:**
+
+```json
+[
+  {
+    "id": "uuid",
+    "name": "Code Reviewer",
+    "description": "Reviews code for bugs and best practices",
+    "model": "claude-sonnet-4-20250514",
+    "provider": "anthropic",
+    "system_prompt": "You are a senior code reviewer...",
+    "temperature": 0.3,
+    "max_tokens": 4096,
+    "tags": ["code", "review"],
+    "workspace_id": "uuid",
+    "created_at": "2026-01-15T10:00:00Z",
+    "updated_at": "2026-01-15T10:00:00Z"
+  }
+]
+```
+
+### Create Agent
+
+```http
+POST /rest/v1/agents
+Content-Type: application/json
+
+{
+  "name": "Code Reviewer",
+  "model": "claude-sonnet-4-20250514",
+  "provider": "anthropic",
+  "system_prompt": "You are a senior code reviewer...",
+  "workspace_id": "your-workspace-id"
+}
+```
+
+### Update Agent
+
+```http
+PATCH /rest/v1/agents?id=eq.{agent_id}
+Content-Type: application/json
+
+{
+  "name": "Updated Name",
+  "temperature": 0.5
+}
+```
+
+### Delete Agent
+
+```http
+DELETE /rest/v1/agents?id=eq.{agent_id}
+```
+
+---
+
+## Tasks
+
+### List Tasks
+
+```http
+GET /rest/v1/tasks?select=*&order=created_at.desc
+```
+
+**Query parameters for filtering:**
+
+| Parameter | Example | Description |
+|-----------|---------|-------------|
+| `status` | `eq.running` | Filter by status |
+| `priority` | `eq.high` | Filter by priority |
+| `agent_id` | `eq.{uuid}` | Filter by assigned agent |
+
+### Create Task
+
+```http
+POST /rest/v1/tasks
+Content-Type: application/json
+
+{
+  "title": "Review PR #42",
+  "description": "Review the authentication changes",
+  "agent_id": "uuid",
+  "priority": "high",
+  "workspace_id": "your-workspace-id"
+}
+```
+
+**Task statuses:** `pending`, `running`, `completed`, `failed`, `cancelled`
+
+**Task priorities:** `low`, `medium`, `high`, `critical`
+
+### Get Task Detail
+
+```http
+GET /rest/v1/tasks?id=eq.{task_id}&select=*
+```
+
+---
+
+## Teams
+
+### List Teams
+
+```http
+GET /rest/v1/teams?select=*
+```
+
+### Create Team
+
+```http
+POST /rest/v1/teams
+Content-Type: application/json
+
+{
+  "name": "Content Pipeline",
+  "description": "Research → Write → Edit",
+  "mode": "pipeline",
+  "workspace_id": "your-workspace-id"
+}
+```
+
+### Team Runs
+
+```http
+GET /rest/v1/team_runs?team_id=eq.{team_id}&select=*&order=created_at.desc
+```
+
+---
+
+## Usage Records
+
+### Query Usage
+
+```http
+GET /rest/v1/usage_records?select=*&created_at=gte.2026-01-01&order=created_at.desc
+```
+
+**Response fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_id` | uuid | Associated task |
+| `agent_id` | uuid | Agent that ran |
+| `provider` | string | LLM provider |
+| `model` | string | Model used |
+| `prompt_tokens` | integer | Input tokens |
+| `completion_tokens` | integer | Output tokens |
+| `estimated_cost_usd` | decimal | Estimated cost |
+| `billing_model` | string | `per-token` or `subscription-quota` |
+
+---
+
+## Marketplace
+
+### Browse Agents
+
+```http
+GET /rest/v1/agents?is_marketplace=eq.true&select=*
+```
+
+### Install Agent (RPC)
+
+```http
+POST /rest/v1/rpc/increment_install_count
+Content-Type: application/json
+
+{
+  "agent_row_id": "uuid"
+}
+```
+
+---
+
+## Rate Limits
+
+The Supabase free tier includes:
+- **500 requests/minute** per API key
+- **50,000 requests/month** total
+
+For higher limits, upgrade your Supabase plan.
+
+## Error Handling
+
+All errors follow the standard Supabase/PostgREST format:
+
+```json
+{
+  "code": "PGRST301",
+  "message": "Row not found",
+  "details": null,
+  "hint": null
+}
+```
+
+Common error codes:
+
+| HTTP Status | Meaning |
+|-------------|---------|
+| `401` | Missing or invalid API key |
+| `403` | Row-Level Security denied access |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate key) |
+| `422` | Validation error |