diff --git a/README.md b/README.md
index fc581740..be0fbab0 100644
--- 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
new file mode 100644
index 00000000..c5511688
--- /dev/null
+++ 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
new file mode 100644
index 00000000..df2f0fb0
--- /dev/null
+++ 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 |
diff --git a/docs/pipeline-teams.md b/docs/pipeline-teams.md
new file mode 100644
index 00000000..692894da
--- /dev/null
+++ b/docs/pipeline-teams.md
@@ -0,0 +1,114 @@
+# Pipeline Teams Guide
+
+Pipeline teams let you chain multiple agents together, where each agent's output feeds into the next. This is ideal for multi-step workflows like research → analysis → report generation.
+
+## How Pipelines Work
+
+```
+Input → Agent A → Agent B → Agent C → Final Output
+         (step 1)   (step 2)   (step 3)
+```
+
+Each step receives:
+- The **original task input**
+- The **previous step's output** (if not the first step)
+- Its own **step instructions** and **expected output format**
+
+## Creating a Pipeline Team
+
+1. Navigate to **Teams → New Team**
+2. Give it a name and description
+3. Select **Pipeline** as the team mode
+4. Add steps in order — each step maps to an agent
+
+### Step Configuration
+
+| Field | Description |
+|-------|-------------|
+| **Agent** | Which agent executes this step |
+| **Step Name** | Label for this step (e.g., "Research") |
+| **Instructions** | What this specific step should do |
+| **Expected Output** | Format the agent should respond in |
+| **On Failure** | `retry` (up to max), `stop` (halt pipeline), or `skip` |
+| **Max Retries** | How many times to retry on failure (0–5) |
+
+## Example: Content Pipeline
+
+A three-step pipeline for generating blog posts:
+
+### Step 1: Research Agent
+- **Agent**: Research Specialist (Claude Sonnet)
+- **Instructions**: "Research the given topic. Find 5 key facts, statistics, and expert quotes."
+- **Expected Output**: "Bullet-point list of findings with sources"
+- **On Failure**: retry (max 2)
+
+### Step 2: Writer Agent
+- **Agent**: Content Writer (GPT-4o)
+- **Instructions**: "Using the research provided, write a 1000-word blog post. Use an engaging, professional tone."
+- **Expected Output**: "Markdown-formatted blog post with headers"
+- **On Failure**: retry (max 1)
+
+### Step 3: Editor Agent
+- **Agent**: Copy Editor (Claude Haiku)
+- **Instructions**: "Review and polish the blog post. Fix grammar, improve flow, ensure factual accuracy against the research."
+- **Expected Output**: "Final polished blog post in Markdown"
+- **On Failure**: stop
+
+## Running a Pipeline
+
+1. Go to the team detail page
+2. Click **Run Pipeline**
+3. Enter the task input (e.g., "Write a blog post about AI in healthcare")
+4. Watch each step execute in real-time
+
+The run detail page shows:
+- Overall pipeline status
+- Per-step status and output
+- Token usage per step
+- Total execution time
+
+## Pipeline Context
+
+Each step automatically receives context about its position:
+
+```
+## Task
+[Original input from the user]
+
+## Previous Step Output
+[Output from the previous step]
+
+## Your Instructions
+[Step-specific instructions]
+
+## Expected Output Format
+[What format to respond in]
+
+## Pipeline Context
+This is step 3 in a multi-step pipeline. 2 previous steps have completed.
+```
+
+## Failure Handling
+
+| Strategy | Behavior |
+|----------|----------|
+| **Retry** | Re-runs the step (up to max retries). Useful for transient API errors. |
+| **Stop** | Halts the entire pipeline. The run is marked as failed. |
+| **Skip** | Marks the step as skipped and continues to the next step. The next step won't receive output from the skipped step. |
+
+## Best Practices
+
+1. **Start simple** — Begin with 2-3 steps and add complexity gradually
+2. **Specialized agents** — Each agent should do one thing well
+3. **Clear handoffs** — Define expected output format so the next step knows what to expect
+4. **Use retry for API steps** — LLM APIs can have transient failures
+5. **Use stop for critical steps** — If step 1 fails, there's no point running step 2
+6. **Monitor costs** — Each step uses tokens; longer pipelines cost more
+
+## Monitoring
+
+View pipeline metrics on the **Analytics** page:
+- Total tasks completed per team
+- Average execution time
+- Token usage breakdown by step
+- Cost per pipeline run
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 00000000..d3b554de
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,84 @@
+# Quick Start Guide
+
+Get CrewForm running locally in under 5 minutes.
+
+## Prerequisites
+
+- **Node.js** 20+
+- **npm** 10+
+- **Supabase** account (free tier works) — [supabase.com](https://supabase.com)
+- At least one LLM API key (Anthropic, Google, or OpenAI)
+
+## 1. Clone & Install
+
+```bash
+git clone https://github.com/vincentgrobler/crewform.git
+cd crewform
+npm install
+```
+
+## 2. Supabase Setup
+
+1. Create a new project at [supabase.com/dashboard](https://supabase.com/dashboard)
+2. Go to **Settings → API** and copy your **URL** and **anon key**
+3. Go to **SQL Editor** and run each migration file in order:
+
+```bash
+# Files are in supabase/migrations/, run them in numeric order:
+# 001_initial_schema.sql
+# 002_rls_policies.sql
+# ... through to the latest
+```
+
+## 3. Environment
+
+```bash
+cp .env.example .env.local
+```
+
+Edit `.env.local` with your values:
+
+```env
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+VITE_APP_URL=http://localhost:5173
+VITE_ENCRYPTION_KEY=generate-a-32-byte-hex-key
+```
+
+> **Generate an encryption key:** `openssl rand -hex 32`
+
+## 4. Start Development
+
+```bash
+npm run dev
+```
+
+Visit [http://localhost:5173](http://localhost:5173) and sign up for an account.
+
+## 5. Task Runner (for AI execution)
+
+The task runner processes agent tasks. In a separate terminal:
+
+```bash
+cd task-runner
+npm install
+cp .env.example .env
+# Add your LLM API keys to .env
+npm start
+```
+
+## 6. Add Your First Agent
+
+1. Navigate to **Agents → New Agent**
+2. Give it a name and description
+3. Select a model (e.g., `claude-sonnet-4-20250514`)
+4. Write a system prompt
+5. Go to **Settings → API Keys** and add your provider key
+6. Create a task from the **Tasks** page to test it
+
+## What's Next?
+
+- [Agents Guide](./agents.md) — Deep dive into agent configuration
+- [Pipeline Teams Guide](./pipeline-teams.md) — Multi-agent workflows
+- [API Reference](./api-reference.md) — REST API documentation
+- [Self-Hosting Guide](./self-hosting.md) — Docker production deployment