diff --git a/crates/executors/default_mcp.json b/crates/executors/default_mcp.json
index cedf445f..8a0d1e32 100644
--- a/crates/executors/default_mcp.json
+++ b/crates/executors/default_mcp.json
@@ -24,7 +24,7 @@
"vibe_kanban": {
"name": "Vibe Kanban",
"description": "Create, update and delete Vibe Kanban tasks",
- "url": "https://www.vibekanban.com/docs/user-guide/vibe-kanban-mcp-server",
+ "url": "https://www.vibekanban.com/docs/integrations/vibe-kanban-mcp-server",
"icon": "viba-kanban-favicon.png"
},
"context7": {
diff --git a/docs/ai-tools/cursor.mdx b/docs/AGENTS.md
similarity index 84%
rename from docs/ai-tools/cursor.mdx
rename to docs/AGENTS.md
index fbb77616..cc3f9bf6 100644
--- a/docs/ai-tools/cursor.mdx
+++ b/docs/AGENTS.md
@@ -1,30 +1,16 @@
----
-title: "Cursor setup"
-description: "Configure Cursor for your documentation workflow"
-icon: "arrow-pointer"
----
-
-Use Cursor to help write and maintain your documentation. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components.
-
-## Prerequisites
-
-- Cursor editor installed
-- Access to your documentation repository
-
-## Project rules
-
-Create project rules that all team members can use. In your documentation repository root:
-
-```bash
-mkdir -p .cursor
-```
-
-Create `.cursor/rules.md`:
-
-````markdown
# Mintlify technical writing rule
-You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
+You are an AI writing assistant specialised in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
+
+## Working relationship
+- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
+- ALWAYS ask for clarification rather than making assumptions
+- NEVER lie, guess, or make up information
+
+## Project context
+- Format: MDX files with YAML frontmatter
+- Config: docs.json for navigation, theme, settings
+- Components: Mintlify components
## Core writing principles
@@ -36,10 +22,11 @@ You are an AI writing assistant specialized in creating exceptional technical do
- Employ present tense for current states, future tense for outcomes
- Avoid jargon unless necessary and define terms when first used
- Maintain consistent terminology throughout all documentation
-- Keep sentences concise while providing necessary context
+- Keep sentences concise whilst providing necessary context
- Use parallel structure in lists, headings, and procedures
+- Use British English spelling and grammar
-### Content organization standards
+### Content organisation standards
- Lead with the most important information (inverted pyramid structure)
- Use progressive disclosure: basic concepts before advanced ones
@@ -48,8 +35,11 @@ You are an AI writing assistant specialized in creating exceptional technical do
- Provide expected outcomes for each major step
- Use descriptive, keyword-rich headings for navigation and SEO
- Group related information logically with clear section breaks
+- Make content evergreen when possible
+- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
+- Check existing patterns for consistency
-### User-centered approach
+### User-centred approach
- Focus on user goals and outcomes rather than system features
- Anticipate common questions and address them proactively
@@ -57,8 +47,22 @@ You are an AI writing assistant specialized in creating exceptional technical do
- Write for scannability with clear headings, lists, and white space
- Include verification steps to confirm success
+### Frontmatter requirements for pages
+- title: Clear, descriptive page title
+- description: Concise summary for SEO/navigation
+
+### Do not
+- Skip frontmatter on any MDX file
+- Use absolute URLs for internal links
+- Include untested code examples
+- Make assumptions - always ask for clarification
+
## Mintlify component reference
+### docs.json
+
+- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
+
### Callout components
#### Note - Additional helpful information
@@ -102,7 +106,7 @@ const apiConfig = {
baseURL: 'https://api.example.com',
timeout: 5000,
headers: {
- 'Authorization': `Bearer ${process.env.API_TOKEN}`
+ 'Authorisation': `Bearer ${process.env.API_TOKEN}`
}
};
```
@@ -114,19 +118,19 @@ Example of a code group:
```javascript Node.js
const response = await fetch('/api/endpoint', {
- headers: { Authorization: `Bearer ${apiKey}` }
+ headers: { Authorisation: `Bearer ${apiKey}` }
});
```
```python Python
import requests
-response = requests.get('/api/endpoint',
- headers={'Authorization': f'Bearer {api_key}'})
+response = requests.get('/api/endpoint',
+ headers={'Authorisation': f'Bearer {api_key}'})
```
```curl cURL
curl -X GET '/api/endpoint' \
- -H 'Authorization: Bearer YOUR_API_KEY'
+ -H 'Authorisation: Bearer YOUR_API_KEY'
```
@@ -146,7 +150,7 @@ curl -X POST 'https://api.example.com/users' \
```json Success
{
"id": "user_123",
- "name": "John Doe",
+ "name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
@@ -162,7 +166,7 @@ Example of step-by-step instructions:
Run `npm install` to install required packages.
-
+
Verify installation by running `npm list`.
@@ -170,11 +174,11 @@ Example of step-by-step instructions:
Create a `.env` file with your API credentials.
-
+
```bash
API_KEY=your_api_key_here
```
-
+
Never commit API keys to version control.
@@ -229,7 +233,7 @@ Example of accordion groups:
-### Cards and columns for emphasizing information
+### Cards and columns for emphasising information
Example of cards and card groups:
@@ -265,7 +269,7 @@ User's email address. Must be valid and unique within the system.
Maximum number of results to return. Range: 1-100.
-
+
Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
@@ -295,12 +299,12 @@ Complete user object with all associated data.
User profile information including personal details.
-
+
User's first name as entered during registration.
-
+
URL to user's profile picture. Returns null if no avatar is set.
@@ -390,14 +394,6 @@ description: "Concise description explaining page purpose and value"
- Add explanatory comments for complex logic
- Never include real API keys or secrets in code examples
-### API documentation requirements
-
-- Document all parameters including optional ones with clear descriptions
-- Show both success and error response examples with realistic data
-- Include rate limiting information with specific limits
-- Provide authentication examples showing proper format
-- Explain all HTTP status codes and error handling
-- Cover complete request/response cycles
### Accessibility requirements
@@ -405,7 +401,7 @@ description: "Concise description explaining page purpose and value"
- Use specific, actionable link text instead of "click here"
- Ensure proper heading hierarchy starting with H2
- Provide keyboard navigation considerations
-- Use sufficient color contrast in examples and visuals
+- Use sufficient colour contrast in examples and visuals
- Structure content for easy scanning with headers and lists
## Component selection logic
@@ -417,4 +413,3 @@ description: "Concise description explaining page purpose and value"
- Use **RequestExample/ResponseExample** specifically for API endpoint documentation
- Use **ParamField** for API parameters, **ResponseField** for API responses
- Use **Expandable** for nested object properties or hierarchical information
-````
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/docs/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index 66c5f11f..45c504c9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,16 +1,6 @@
# Mintlify Starter Kit
-Use the starter kit to get your docs deployed and ready to customize.
-
-Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
-
-- Guide pages
-- Navigation
-- Customizations
-- API reference pages
-- Use of popular components
-
-**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
+**[Mintlify Quickstart Guide](https://starter.mintlify.com/quickstart)**
## Development
diff --git a/docs/ai-tools/claude-code.mdx b/docs/ai-tools/claude-code.mdx
deleted file mode 100644
index bdc4e04b..00000000
--- a/docs/ai-tools/claude-code.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: "Claude Code setup"
-description: "Configure Claude Code for your documentation workflow"
-icon: "asterisk"
----
-
-Claude Code is Anthropic's official CLI tool. This guide will help you set up Claude Code to help you write and maintain your documentation.
-
-## Prerequisites
-
-- Active Claude subscription (Pro, Max, or API access)
-
-## Setup
-
-1. Install Claude Code globally:
-
- ```bash
- npm install -g @anthropic-ai/claude-code
-```
-
-2. Navigate to your docs directory.
-3. (Optional) Add the `CLAUDE.md` file below to your project.
-4. Run `claude` to start.
-
-## Create `CLAUDE.md`
-
-Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards:
-
-````markdown
-# Mintlify documentation
-
-## Working relationship
-- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
-- ALWAYS ask for clarification rather than making assumptions
-- NEVER lie, guess, or make up information
-
-## Project context
-- Format: MDX files with YAML frontmatter
-- Config: docs.json for navigation, theme, settings
-- Components: Mintlify components
-
-## Content strategy
-- Document just enough for user success - not too much, not too little
-- Prioritize accuracy and usability of information
-- Make content evergreen when possible
-- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
-- Check existing patterns for consistency
-- Start by making the smallest reasonable changes
-
-## Frontmatter requirements for pages
-- title: Clear, descriptive page title
-- description: Concise summary for SEO/navigation
-
-## Writing standards
-- Second-person voice ("you")
-- Prerequisites at start of procedural content
-- Test all code examples before publishing
-- Match style and formatting of existing pages
-- Include both basic and advanced use cases
-- Language tags on all code blocks
-- Alt text on all images
-- Relative paths for internal links
-
-## Git workflow
-- NEVER use --no-verify when committing
-- Ask how to handle uncommitted changes before starting
-- Create a new branch when no clear branch exists for changes
-- Commit frequently throughout development
-- NEVER skip or disable pre-commit hooks
-
-## Do not
-- Skip frontmatter on any MDX file
-- Use absolute URLs for internal links
-- Include untested code examples
-- Make assumptions - always ask for clarification
-````
diff --git a/docs/ai-tools/windsurf.mdx b/docs/ai-tools/windsurf.mdx
deleted file mode 100644
index fce12bfd..00000000
--- a/docs/ai-tools/windsurf.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: "Windsurf setup"
-description: "Configure Windsurf for your documentation workflow"
-icon: "water"
----
-
-Configure Windsurf's Cascade AI assistant to help you write and maintain documentation. This guide shows how to set up Windsurf specifically for your Mintlify documentation workflow.
-
-## Prerequisites
-
-- Windsurf editor installed
-- Access to your documentation repository
-
-## Workspace rules
-
-Create workspace rules that provide Windsurf with context about your documentation project and standards.
-
-Create `.windsurf/rules.md` in your project root:
-
-````markdown
-# Mintlify technical writing rule
-
-## Project context
-
-- This is a documentation project on the Mintlify platform
-- We use MDX files with YAML frontmatter
-- Navigation is configured in `docs.json`
-- We follow technical writing best practices
-
-## Writing standards
-
-- Use second person ("you") for instructions
-- Write in active voice and present tense
-- Start procedures with prerequisites
-- Include expected outcomes for major steps
-- Use descriptive, keyword-rich headings
-- Keep sentences concise but informative
-
-## Required page structure
-
-Every page must start with frontmatter:
-
-```yaml
----
-title: "Clear, specific title"
-description: "Concise description for SEO and navigation"
----
-```
-
-## Mintlify components
-
-### Callouts
-
-- `` for helpful supplementary information
-- `` for important cautions and breaking changes
-- `` for best practices and expert advice
-- `` for neutral contextual information
-- `` for success confirmations
-
-### Code examples
-
-- When appropriate, include complete, runnable examples
-- Use `` for multiple language examples
-- Specify language tags on all code blocks
-- Include realistic data, not placeholders
-- Use `` and `` for API docs
-
-### Procedures
-
-- Use `` component for sequential instructions
-- Include verification steps with `` components when relevant
-- Break complex procedures into smaller steps
-
-### Content organization
-
-- Use `` for platform-specific content
-- Use `` for progressive disclosure
-- Use `` and `` for highlighting content
-- Wrap images in `` components with descriptive alt text
-
-## API documentation requirements
-
-- Document all parameters with ``
-- Show response structure with ``
-- Include both success and error examples
-- Use `` for nested object properties
-- Always include authentication examples
-
-## Quality standards
-
-- Test all code examples before publishing
-- Use relative paths for internal links
-- Include alt text for all images
-- Ensure proper heading hierarchy (start with h2)
-- Check existing patterns for consistency
-````
diff --git a/docs/api-reference/endpoint/create.mdx b/docs/api-reference/endpoint/create.mdx
deleted file mode 100644
index 5689f1b6..00000000
--- a/docs/api-reference/endpoint/create.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Create Plant'
-openapi: 'POST /plants'
----
diff --git a/docs/api-reference/endpoint/delete.mdx b/docs/api-reference/endpoint/delete.mdx
deleted file mode 100644
index 657dfc87..00000000
--- a/docs/api-reference/endpoint/delete.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Delete Plant'
-openapi: 'DELETE /plants/{id}'
----
diff --git a/docs/api-reference/endpoint/get.mdx b/docs/api-reference/endpoint/get.mdx
deleted file mode 100644
index 56aa09ec..00000000
--- a/docs/api-reference/endpoint/get.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Get Plants'
-openapi: 'GET /plants'
----
diff --git a/docs/api-reference/endpoint/webhook.mdx b/docs/api-reference/endpoint/webhook.mdx
deleted file mode 100644
index 32913402..00000000
--- a/docs/api-reference/endpoint/webhook.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'New Plant'
-openapi: 'WEBHOOK /plant/webhook'
----
diff --git a/docs/api-reference/introduction.mdx b/docs/api-reference/introduction.mdx
deleted file mode 100644
index c835b78b..00000000
--- a/docs/api-reference/introduction.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: 'Introduction'
-description: 'Example section for showcasing API endpoints'
----
-
-
- If you're not looking to build API reference documentation, you can delete
- this section by removing the api-reference folder.
-
-
-## Welcome
-
-There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.
-
-
- View the OpenAPI specification file
-
-
-## Authentication
-
-All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
-
-```json
-"security": [
- {
- "bearerAuth": []
- }
-]
-```
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json
deleted file mode 100644
index da5326ef..00000000
--- a/docs/api-reference/openapi.json
+++ /dev/null
@@ -1,217 +0,0 @@
-{
- "openapi": "3.1.0",
- "info": {
- "title": "OpenAPI Plant Store",
- "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification",
- "license": {
- "name": "MIT"
- },
- "version": "1.0.0"
- },
- "servers": [
- {
- "url": "http://sandbox.mintlify.com"
- }
- ],
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "paths": {
- "/plants": {
- "get": {
- "description": "Returns all plants from the system that the user has access to",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "The maximum number of results to return",
- "schema": {
- "type": "integer",
- "format": "int32"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Plant response",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/Plant"
- }
- }
- }
- }
- },
- "400": {
- "description": "Unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- }
- },
- "post": {
- "description": "Creates a new plant in the store",
- "requestBody": {
- "description": "Plant to add to the store",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/NewPlant"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "plant response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Plant"
- }
- }
- }
- },
- "400": {
- "description": "unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- }
- }
- },
- "/plants/{id}": {
- "delete": {
- "description": "Deletes a single plant based on the ID supplied",
- "parameters": [
- {
- "name": "id",
- "in": "path",
- "description": "ID of plant to delete",
- "required": true,
- "schema": {
- "type": "integer",
- "format": "int64"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "Plant deleted",
- "content": {}
- },
- "400": {
- "description": "unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- }
- }
- }
- },
- "webhooks": {
- "/plant/webhook": {
- "post": {
- "description": "Information about a new plant added to the store",
- "requestBody": {
- "description": "Plant added to the store",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/NewPlant"
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Return a 200 status to indicate that the data was received successfully"
- }
- }
- }
- }
- },
- "components": {
- "schemas": {
- "Plant": {
- "required": [
- "name"
- ],
- "type": "object",
- "properties": {
- "name": {
- "description": "The name of the plant",
- "type": "string"
- },
- "tag": {
- "description": "Tag to specify the type",
- "type": "string"
- }
- }
- },
- "NewPlant": {
- "allOf": [
- {
- "$ref": "#/components/schemas/Plant"
- },
- {
- "required": [
- "id"
- ],
- "type": "object",
- "properties": {
- "id": {
- "description": "Identification number of the plant",
- "type": "integer",
- "format": "int64"
- }
- }
- }
- ]
- },
- "Error": {
- "required": [
- "error",
- "message"
- ],
- "type": "object",
- "properties": {
- "error": {
- "type": "integer",
- "format": "int32"
- },
- "message": {
- "type": "string"
- }
- }
- }
- },
- "securitySchemes": {
- "bearerAuth": {
- "type": "http",
- "scheme": "bearer"
- }
- }
- }
-}
\ No newline at end of file
diff --git a/docs/configuration-customisation/agent-configurations.mdx b/docs/configuration-customisation/agent-configurations.mdx
new file mode 100644
index 00000000..6d1ffe17
--- /dev/null
+++ b/docs/configuration-customisation/agent-configurations.mdx
@@ -0,0 +1,215 @@
+---
+title: "Agent Profiles & Configuration"
+description: "Configure and customise coding agent variants with different settings for planning, models, and sandbox permissions"
+---
+
+Agent profiles let you define multiple named variants for each supported coding agent. Variants capture configuration differences like planning mode, model choice, and sandbox permissions that you can quickly select when creating attempts.
+
+
+Agent profiles are used throughout Vibe Kanban wherever agents run: onboarding, default settings, attempt creation, and follow-ups.
+
+
+## Configuration Access
+
+You can configure agent profiles in two ways through Settings → Agents:
+
+
+
+ Use the guided interface with form fields for each agent setting.
+
+
+
+
+
+
+
+ Edit the underlying `profiles.json` file directly for advanced configurations.
+
+
+
+
+
+
+
+
+The configuration page displays the exact file path where your settings are stored. Vibe Kanban saves only your overrides whilst preserving built-in defaults.
+
+
+## Configuration Structure
+
+The profiles configuration uses a JSON structure with an `executors` object containing agent variants:
+
+```json profiles.json
+{
+ "executors": {
+ "CLAUDE_CODE": {
+ "DEFAULT": { "CLAUDE_CODE": { "dangerously_skip_permissions": true } },
+ "PLAN": { "CLAUDE_CODE": { "plan": true } },
+ "ROUTER": { "CLAUDE_CODE": { "claude_code_router": true, "dangerously_skip_permissions": true } }
+ },
+ "GEMINI": {
+ "DEFAULT": { "GEMINI": { "model": "default", "yolo": true } },
+ "FLASH": { "GEMINI": { "model": "flash", "yolo": true } }
+ },
+ "CODEX": {
+ "DEFAULT": { "CODEX": { "sandbox": "danger-full-access" } },
+ "HIGH": { "CODEX": { "sandbox": "danger-full-access", "model_reasoning_effort": "high" } }
+ }
+ }
+}
+```
+
+
+
+ - **Variant names**: Case-insensitive and normalised to SCREAMING_SNAKE_CASE
+ - **DEFAULT variant**: Reserved and always present for each agent
+ - **Custom variants**: Add new variants like `PLAN`, `FLASH`, `HIGH` as needed
+ - **Built-in protection**: Cannot remove built-in executors, but can override values
+
+
+
+ - Your custom settings override built-in defaults
+ - Built-in configurations remain available as fallbacks
+ - Each variant contains a complete configuration object for its agent
+
+
+
+## Agent Configuration Options
+
+
+
+
+ Enable planning mode for complex tasks
+
+
+
+ Route requests across multiple Claude Code instances
+
+
+
+ Skip permission prompts (use with caution)
+
+
+ [View full CLI reference →](https://docs.anthropic.com/en/docs/claude-code/cli-reference#cli-flags)
+
+
+
+
+ Choose model variant: `"default"` or `"flash"`
+
+
+
+ Run without confirmations
+
+
+ [View full CLI reference →](https://google-gemini.github.io/gemini-cli/)
+
+
+
+
+ Allow all actions without restrictions (unsafe)
+
+
+ [View full documentation →](https://ampcode.com/manual#cli)
+
+
+
+
+ Execution environment: `"read-only"`, `"workspace-write"`, or `"danger-full-access"`
+
+
+
+ Approval level: `"untrusted"`, `"on-failure"`, `"on-request"`, or `"never"`
+
+
+
+ Reasoning depth: `"low"`, `"medium"`, or `"high"`
+
+
+
+ Summary style: `"auto"`, `"concise"`, `"detailed"`, or `"none"`
+
+
+ [View full documentation →](https://github.com/openai/codex)
+
+
+
+
+ Force execution without confirmation
+
+
+
+ Specify model to use
+
+
+ [View full CLI reference →](https://docs.cursor.com/en/cli/reference/parameters)
+
+
+
+
+ Specify model to use
+
+
+
+ Choose agent type
+
+
+ [View full documentation →](https://opencode.ai/docs/cli/#flags-1)
+
+
+
+
+ Run without confirmations
+
+
+ [View full documentation →](https://qwenlm.github.io/qwen-code-docs/en/cli/index)
+
+
+
+### Universal Options
+
+These options work across multiple agent types:
+
+
+Text appended to the system prompt
+
+
+
+Override the underlying CLI command
+
+
+
+Additional CLI arguments to pass
+
+
+
+Options prefixed with "dangerously_" bypass safety confirmations and can perform destructive actions. Use with extreme caution.
+
+
+## Using Agent Configurations
+
+
+
+ Set your default agent and variant in **Settings → General → Default Agent Configuration** for consistent behaviour across all attempts.
+
+
+
+ Override defaults when creating attempts by selecting different agent/variant combinations in the attempt dialogue.
+
+
+
+## Related Configuration
+
+
+MCP (Model Context Protocol) servers are configured separately under **Settings → MCP Servers** but work alongside agent profiles to extend functionality.
+
+
+
+
+ Configure MCP servers within Vibe Kanban for your coding agents
+
+
+
+ Connect external MCP clients to Vibe Kanban's MCP server
+
+
diff --git a/docs/configuration-customisation/creating-task-templates.mdx b/docs/configuration-customisation/creating-task-templates.mdx
new file mode 100644
index 00000000..fdd18c5c
--- /dev/null
+++ b/docs/configuration-customisation/creating-task-templates.mdx
@@ -0,0 +1,68 @@
+---
+title: "Creating Task Templates"
+description: "Create reusable task formats that speed up task creation. You can create templates globally (across all projects) or for specific projects."
+---
+
+## Managing global task templates
+
+Access global templates from **Global Settings → Task Templates**. These templates are available across every project in your workspace.
+
+
+
+
+
+
+
+ Click **Add Template** to create a new global template.
+
+
+
+ Use the edit icon (✏️) to modify template content.
+
+
+
+ Click the delete icon (🗑️) to remove templates you no longer need.
+
+
+
+## Managing project task templates
+
+Create templates scoped to individual projects for project-specific workflows.
+
+
+
+
+
+
+
+ 1. Open your project
+ 2. Click the library icon in the project header
+ 3. Select **Manage Templates**
+
+
+
+ Use **Add Template**, **Edit** (✏️), and **Remove** (🗑️) controls to manage project-specific templates.
+
+
+
+## Using templates
+
+Apply templates when creating tasks to prefill content and maintain consistency.
+
+
+
+ When creating a new task, click the **Use a template** dropdown.
+
+
+
+ Select from your global or project-specific templates.
+
+
+ The template automatically prefills the task title and description.
+
+
+
+
+
+Global templates appear in all projects, whilst project templates only appear in their specific project. Use global templates for common task types and project templates for specialised workflows.
+
diff --git a/docs/configuration-customisation/global-settings.mdx b/docs/configuration-customisation/global-settings.mdx
new file mode 100644
index 00000000..d4c11d5b
--- /dev/null
+++ b/docs/configuration-customisation/global-settings.mdx
@@ -0,0 +1,70 @@
+---
+title: "Global Settings"
+description: "Configure application-wide settings including themes, agents, GitHub integration, and more"
+sidebarTitle: "Settings"
+---
+
+You can configure application-wide settings via the **Settings** page. To access it, click the ⚙️ icon in the sidebar or select "Settings" from the top-right menu.
+
+
+
+
+
+## Themes
+
+Switch between light and dark themes to suit your preference.
+
+## Default Agent Configuration
+
+Choose the default agent and variant for new task attempts. This profile is pre-selected when creating new task attempts and follow-ups.
+
+1. **Select an agent** (e.g., Claude Code, Gemini CLI, Codex)
+2. **Choose a variant** if available (e.g., Default, Plan, Router)
+
+
+You can override the default agent configuration per attempt in the create attempt dialog.
+
+
+## Editor Integration
+
+Configure integration with your preferred code editor (e.g., VS Code) for a seamless development workflow.
+
+## GitHub Integration
+
+Link your GitHub account by providing a Personal Access Token (PAT) to enable:
+
+- Automatic branch management
+- Pull request creation and tracking
+- Status synchronisation directly from Vibe Kanban
+
+## Notifications
+
+Toggle sound effects and push notifications to stay informed about task status changes.
+
+## Telemetry
+
+Enable or disable telemetry data collection to help improve Vibe Kanban.
+
+## Task Templates
+
+Manage global task templates to accelerate task creation across all projects. Templates allow you to define reusable titles and descriptions for common tasks.
+
+
+ Complete guide to creating and managing task templates
+
+
+## Agent Settings (Profiles & Variants)
+
+Define and customise agent variants under **Settings → Agents**. Variants let you maintain multiple configurations for the same agent (for example, a Claude Code "PLAN" variant).
+
+
+ Detailed guide with examples for configuring agent variants
+
+
+## Safety & Disclaimers
+
+Manage acknowledgments and reset options for onboarding, safety disclaimers, and telemetry notices.
+
+- **Onboarding**: Reset the onboarding process to rerun the initial setup.
+- **Safety Disclaimer**: Reset or review the safety disclaimer prompt.
+- **Telemetry Notice**: Reset or review the telemetry data collection acknowledgment.
diff --git a/docs/configuration-customisation/keyboard-shortcuts.mdx b/docs/configuration-customisation/keyboard-shortcuts.mdx
new file mode 100644
index 00000000..f54fbaed
--- /dev/null
+++ b/docs/configuration-customisation/keyboard-shortcuts.mdx
@@ -0,0 +1,58 @@
+---
+title: "Keyboard Shortcuts"
+description: "Complete guide to keyboard shortcuts for efficient navigation and interaction in Vibe Kanban"
+---
+
+Vibe Kanban provides comprehensive keyboard shortcuts to help you navigate and interact with the application efficiently. These shortcuts are organised by scope and context.
+
+## Platform Keys
+
+- **⌘** = Mac Command key
+- **Ctrl** = Windows/Linux Control key
+
+## Global Shortcuts
+
+These shortcuts work anywhere in the application (unless you're typing in an input field):
+
+| Shortcut | Action | Description |
+|----------|--------|-------------|
+| `C` | Create Task | Opens the Task Form dialog to create a new task |
+| `⌘/Ctrl + S` | Focus Search | Puts keyboard focus into the global search input |
+
+## Board Navigation
+
+These shortcuts work when a task card is highlighted with the blue focus ring:
+
+| Shortcut | Action | Description |
+|----------|--------|-------------|
+| `↑` / `↓` | Vertical Navigation | Move focus to previous/next task in the current column |
+| `←` / `→` | Horizontal Navigation | Move focus to first task in previous/next non-empty column |
+| `Enter` / `Space` | Open Task | Open the Task Details panel for the focused task |
+| `Backspace` | Delete Task | Delete the currently focused task |
+
+## Form Submission
+
+These shortcuts work in various forms and dialogs:
+
+| Shortcut | Action | Context |
+|----------|--------|---------|
+| `⌘/Ctrl + Enter` | Submit | Create & Start (Task Form), Save (Template Editor) |
+| `⌘/Ctrl + Enter` | Send | Send follow-up message in Task Details |
+| `⌘/Ctrl + Enter` | Save Comment | Add or save comment in Diff Review |
+| `Escape` | Cancel/Clear | Clear draft in follow-up, cancel comment editing |
+
+## Search
+
+| Shortcut | Action | Description |
+|----------|--------|-------------|
+| `⌘/Ctrl + S` | Focus Search | Move cursor to the search input field |
+| `Escape` | Clear Search | Clear search text and remove focus (when in search field) |
+
+*Note: The search field displays a "⌘S" badge to help you discover this shortcut.*
+
+## Tips
+
+- **Focus Indicators**: Look for blue focus rings around task cards to know when board navigation shortcuts are active
+- **Input Fields**: Global shortcuts are disabled when typing in text fields to avoid conflicts
+- **Visual Cues**: Some shortcuts display badges or hints in the interface (like the "⌘S" next to search)
+- **Modifier Keys**: Global shortcuts are disabled when holding Ctrl/⌘/Alt unless the shortcut specifically uses those modifiers
diff --git a/docs/core-features/creating-projects.mdx b/docs/core-features/creating-projects.mdx
new file mode 100644
index 00000000..38c26bcc
--- /dev/null
+++ b/docs/core-features/creating-projects.mdx
@@ -0,0 +1,57 @@
+---
+title: "Creating Projects"
+description: "Learn how to create and configure projects in Vibe Kanban"
+---
+
+Before you can create tasks and execute coding agents, you must create a project.
+
+
+
+
+
+## Creating Your Project
+Click the **Create Project** button to choose from two options:
+- **From existing git repository**: Browse your file system and select from a list of git repositories sorted by recent activity
+- **Create blank project**: Generate a new git repository from scratch
+Each project represents a git repository. After creation, you can configure it with setup scripts, dev server scripts, and other settings.
+
+
+
+After creating a project, you need to press the settings button in the top right to configure project scripts and settings.
+
+
+## Project Settings
+
+Once you've created a project, you can access the project settings by clicking the settings button in the top right corner. From here, you can configure various aspects of your project.
+
+### Setup Scripts
+
+Setup scripts will be run before the coding agent is executed. This is useful for installing dependencies, for example you might run `npm install` or `cargo build`. This will save you time as your agent won't need to figure out that these commands haven't already been run.
+
+
+Each time a coding agent is executed it runs in a [git worktree](https://git-scm.com/docs/git-worktree) which is unlikely to contain your dependencies, configs, .env etc.
+
+
+### Dev Server Scripts
+
+The dev server script is run whenever you press the "run dev server" button. It's useful for quickly reviewing work after a coding agent has run.
+
+### Copy Files
+
+Comma-separated list of files to copy from the original project directory to the worktree. These files will be copied after the worktree is created but before the setup script runs. Useful for environment-specific files like `.env`, configuration files, and local settings.
+
+
+Make sure these files are gitignored or they could get committed!
+
+
+### Project Task Templates
+
+From project settings, you can also configure project-specific task templates. For more details about this feature, see the [project task templates section](/configuration-customisation/creating-task-templates#project-task-templates).
+
+### Cleanup Scripts
+
+Cleanup scripts run after a coding agent finishes. You can use these to tidy up the workspace, remove temporary files, or perform any post-execution cleanup. For example, you might run:
+
+```bash
+npm run clean
+```
diff --git a/docs/core-features/creating-task-attempts.mdx b/docs/core-features/creating-task-attempts.mdx
new file mode 100644
index 00000000..561d0611
--- /dev/null
+++ b/docs/core-features/creating-task-attempts.mdx
@@ -0,0 +1,78 @@
+---
+title: "Creating Task Attempts"
+description: "Understand when and why to create multiple task attempts for fresh restarts with different configurations."
+sidebarTitle: "Creating Task Attempts"
+---
+
+A task attempt represents a single execution of a coding agent against a task. Most tasks only need one attempt, but you may need additional attempts for fresh restarts.
+
+## When to Create New Task Attempts
+
+Create a new task attempt when you want to:
+
+- **Start from scratch** with a different approach after an unsuccessful attempt
+- **Try a different coding agent** (e.g., switching from Claude to Codex)
+- **Use a different agent profile or variant** for specialised behaviour
+- **Work from a different base branch** to incorporate recent changes
+- **Reset the conversation context** for a completely fresh start
+
+
+Most users will only need one attempt per task. Only create additional attempts if the first approach didn't work as expected.
+
+
+## Creating Additional Attempts
+
+To create a new task attempt for an existing task:
+
+
+
+ Open the task that needs a fresh attempt.
+
+
+
+ In the task interface, click the **New Attempt** button.
+
+
+
+ Choose your agent profile, variant, and base branch. These can be different from previous attempts.
+
+
+
+ Click **Create Attempt** to begin a fresh execution with the new configuration.
+
+
+
+## Impact on Subtasks
+
+
+Creating new task attempts affects subtasks. Subtasks are linked to specific task attempts, not tasks themselves.
+
+
+When you create a new task attempt:
+
+- **Existing subtasks** remain linked to their original parent attempt
+- **New subtasks** created from the new attempt will use the new attempt's branch as their base
+- This allows you to maintain different subtask workflows for different approaches
+
+
+For more details about how subtasks work with task attempts, see [Creating Subtasks](/core-features/subtasks).
+
+
+## What Happens Next
+
+After creating a task attempt:
+
+1. **Setup scripts run** automatically (if configured in project settings)
+2. **Agent executes** using your task title and description
+3. **Real-time monitoring** shows progress through streaming logs
+4. **Follow-up questions** can be asked to refine results
+
+For detailed task management after execution, including development server controls, git operations, and monitoring features, see [Task Details Full Screen Mode](/core-features/task-details-full-screen).
+
+## Git Worktrees
+
+Vibe Kanban uses Git worktrees to create isolated environments for each task attempt. These environments are ephemeral and automatically cleaned up after execution completes.
+
+
+Worktrees ensure task attempts don't interfere with each other or your main working directory.
+
diff --git a/docs/core-features/creating-tasks.mdx b/docs/core-features/creating-tasks.mdx
new file mode 100644
index 00000000..918164d4
--- /dev/null
+++ b/docs/core-features/creating-tasks.mdx
@@ -0,0 +1,114 @@
+---
+title: "Creating Tasks"
+description: "Learn how to create and manage tasks on your kanban board, including using templates, starting coding agents, and understanding task states"
+---
+
+
+
+
+
+After creating a project, add tasks by clicking the **plus (+) icon** in the top right of your project kanban page, or by using the keyboard shortcut **`c`**. Creating a task adds it to your kanban board without automatically starting a coding agent.
+
+## Using Templates
+
+
+
+
+
+When adding a task, you can select from your saved templates:
+
+1. Click the **Use a template** dropdown
+2. Choose from available global or project templates
+3. The template automatically populates the task title and description
+
+
+Templates save time by reusing common task structures. Learn more about creating templates in the [Task Templates](/configuration-customisation/creating-task-templates) guide.
+
+
+## Starting Your First Task Attempt
+
+
+
+
+
+To activate a coding agent on your task, create a task attempt:
+
+
+
+ Choose from available agents (e.g., CLAUDE_CODE, GEMINI, CODEX). Your default configuration from Settings is pre-selected.
+
+
+
+ If your selected agent has variants, pick the appropriate one (e.g., DEFAULT, PLAN).
+
+
+
+ Specify which branch the agent should work from. Your current branch is selected by default.
+
+
+
+
+Use **Create & Start** to add the task and immediately create a task attempt with your default settings in one action.
+
+
+### What Happens During Execution
+
+1. **Setup Scripts Run**: Any setup script defined in your project settings runs automatically
+2. **Agent Execution**: The coding agent processes your task using the title and description
+3. **Real-time Monitoring**: Watch progress through streaming logs in the task interface
+4. **Follow-up Questions**: Continue the conversation after execution to refine results
+
+Most tasks only need a single attempt. You'll only need additional attempts if you want to restart from scratch with different settings.
+
+
+For detailed task management after execution, see [Task Details Full Screen Mode](/core-features/task-details-full-screen). To understand when you might need multiple attempts, see [Creating Task Attempts](/core-features/creating-task-attempts).
+
+
+## Creating Tasks via MCP Clients
+
+
+This is not the typical method for creating tasks but can be valuable for bulk task creation or migrating from other systems.
+
+
+Tasks can also be created programmatically using coding agents or MCP (Model Context Protocol) clients such as Claude Desktop or Raycast. This approach is particularly useful for:
+
+- **Bulk task creation** based on existing data or project specifications
+- **Migration from other systems** like Linear, GitHub Issues, or Jira
+- **Automated task generation** from project plans or requirements documents
+
+
+For detailed setup instructions and examples, see the [Vibe Kanban MCP Server](/integrations/vibe-kanban-mcp-server) documentation.
+
+
+### Example MCP Task Creation
+
+Once configured with an MCP client, you can create multiple tasks from a project description:
+
+```
+I need to implement user authentication with:
+- Email/password registration
+- Login with session management
+- Password reset functionality
+- Email verification
+- Protected route middleware
+
+Please create individual tasks for each component.
+```
+
+The MCP client will automatically generate structured tasks in your Vibe Kanban project based on this description.
+
+## Understanding Task Columns
+
+Tasks begin in the "To do" column and move automatically based on their progress:
+
+| Action | Column |
+|--------|---------|
+| Task created | To do |
+| Task attempt started | In Progress |
+| Task attempt completed (success or failure) | In Review |
+| Task attempt merged | Done |
+| PR merged on GitHub | Done |
+
+
+You can manually drag tasks between columns, but this won't trigger any functionality. Task movement is primarily driven by coding agent actions and GitHub integration (which polls every 60 seconds).
+
diff --git a/docs/core-features/reviewing-code-changes.mdx b/docs/core-features/reviewing-code-changes.mdx
new file mode 100644
index 00000000..32029844
--- /dev/null
+++ b/docs/core-features/reviewing-code-changes.mdx
@@ -0,0 +1,100 @@
+---
+title: "Reviewing Code Changes"
+description: "Learn how to review and provide feedback on code changes made by coding agents"
+---
+
+When a coding agent completes a task, it automatically moves to the **In Review** column. This is where you can examine the changes, provide feedback, and ensure the implementation meets your requirements.
+
+
+
+## Opening the Code Review Interface
+
+
+
+ Click on any task in the **In Review** column to open it in full screen mode.
+
+
+
+ Once the task is open, click on the **Diffs** tab to view all the code changes made by the agent.
+
+
+
+## Adding Review Comments
+
+### Line-Specific Comments
+
+To provide feedback on specific lines of code:
+
+
+
+ Find the line you want to comment on in the diffs view.
+
+
+
+ Click the **plus icon** (+) at the beginning of the line to create a review comment.
+
+
+
+
+
+
+
+ Enter your comment in the text field that appears. You can provide suggestions, ask questions, or request changes.
+
+
+
+### Multiple Comments Across Files
+
+You can create several review comments across different files in the same review:
+
+- Add comments to multiple lines within a single file
+- Switch between different changed files and add comments to each
+- All comments will be collected and submitted together as part of your review
+
+
+Review comments are not submitted individually. They are collected and sent as a complete review when you submit your feedback.
+
+
+## General Review Comments
+
+In addition to line-specific feedback, you can provide general comments about the entire implementation:
+
+
+
+ Navigate to the task chat field at the bottom of the review interface.
+
+
+
+ Enter broader comments about the implementation, such as:
+ - Overall code quality assessment
+ - Architectural concerns
+ - Performance considerations
+ - Testing requirements
+
+
+
+## Submitting Your Review
+
+
+
+ Before submitting, review all the line-specific and general comments you've added.
+
+
+
+ Click the **Send** button to send all your feedback to the coding agent.
+
+
+ All comments (line-specific and general) are combined into a single message for the coding agent to address.
+
+
+
+
+ Once submitted, the task returns to the **In Progress** column where the agent will address your feedback and implement the requested changes.
+
+
+
+
diff --git a/docs/core-features/subtasks.mdx b/docs/core-features/subtasks.mdx
new file mode 100644
index 00000000..c6cc35eb
--- /dev/null
+++ b/docs/core-features/subtasks.mdx
@@ -0,0 +1,128 @@
+---
+title: "Creating Subtasks"
+description: "Learn how to create and manage subtasks to break down complex work into smaller, manageable pieces"
+---
+
+Subtasks allow you to break down complex tasks into smaller, more manageable pieces. Each subtask is linked to a specific task attempt and inherits the same project and branch context.
+
+## Creating Subtasks
+
+
+
+
+
+To create a subtask from an existing task attempt:
+
+
+
+ Open the task you want to create subtasks for.
+
+
+
+ In the actions toolbar, click the **Create Subtask** button (marked with a fork icon).
+
+
+
+ The task creation dialog opens with the parent task attempt and base branch automatically set. Add your subtask title and description.
+
+
+
+ Click **Save** to create the subtask. It will appear as a new task on your kanban board.
+
+
+
+
+When you create a subtask, it automatically inherits the base branch from its parent task attempt, ensuring consistency in your development workflow.
+
+
+## Viewing Tasks with Subtasks
+
+
+
+
+
+When viewing a parent task, you can see its subtasks in the **Task Relationships** panel. This collapsible section shows:
+
+- **Child Tasks** with a count (e.g., "CHILD TASKS (1)")
+- Individual subtask titles with links to view them
+- Easy navigation between parent and child tasks
+
+This helps you track progress across all related work items and understand the task hierarchy at a glance.
+
+## Viewing Subtask Details
+
+
+
+
+
+When viewing a subtask, the **Task Relationships** panel displays:
+
+- **Parent Task** section showing the parent task title
+- Direct link to navigate to the parent task
+- Clear visual indication that this is a child task
+- Context about the parent-child relationship
+
+The subtask also shows its own **Create Subtask** button, allowing you to create nested subtasks if needed.
+
+## How Subtasks Work
+
+Subtasks in Vibe Kanban follow these key principles:
+
+### Git Branching Workflow
+
+Subtasks create their own feature branches that can work independently while maintaining connection to the parent task:
+
+```mermaid
+gitGraph
+ commit id: "main"
+ branch feature/parent-task
+ checkout feature/parent-task
+ commit id: "Parent Task Start"
+ commit id: "Initial work"
+
+ branch feature/subtask-1
+ checkout feature/subtask-1
+ commit id: "Subtask 1: Backend API"
+ commit id: "API implementation"
+ commit id: "API tests"
+
+ checkout feature/parent-task
+ branch feature/subtask-2
+ checkout feature/subtask-2
+ commit id: "Subtask 2: Frontend UI"
+ commit id: "Component creation"
+ commit id: "UI styling"
+
+ checkout feature/parent-task
+ branch feature/subtask-3
+ checkout feature/subtask-3
+ commit id: "Subtask 3: Integration"
+ commit id: "Connect API to UI"
+
+ checkout feature/parent-task
+ merge feature/subtask-1
+ merge feature/subtask-2
+ merge feature/subtask-3
+ commit id: "Parent Task Complete"
+
+ checkout main
+ merge feature/parent-task
+```
+
+### Parent-Child Relationships
+
+- Subtasks are linked to specific **task attempts**, not just tasks
+- Each subtask knows which attempt created it
+- Multiple subtasks can be created from the same parent attempt
+
+### Branch Inheritance
+
+- Subtasks automatically inherit the base branch from their parent attempt
+- This ensures subtasks work within the same development context
+- You can modify the branch when creating the subtask if needed
+
+### Independent Task Lifecycle
+
+- Subtasks appear as regular tasks on your kanban board
+- Each subtask has its own lifecycle (To do → In Progress → In Review → Done)
+- Subtasks can have their own task attempts and coding agents
diff --git a/docs/core-features/task-details-full-screen.mdx b/docs/core-features/task-details-full-screen.mdx
new file mode 100644
index 00000000..582e9a8b
--- /dev/null
+++ b/docs/core-features/task-details-full-screen.mdx
@@ -0,0 +1,135 @@
+---
+title: "Task Details Full Screen Mode"
+sidebarTitle: "Full Screen Mode"
+description: "Complete guide to using the task details full screen mode for development workflows, including dev server, git operations, logs, diffs, and process monitoring"
+---
+
+## Accessing Full Screen Mode
+
+Click the **Maximise** button (⛶) in the task details header to expand the view to occupy the full right side of your screen. Some task actions (like "View full diff") automatically switch to full screen mode for better visibility.
+
+
+
+
+
+## Interface Layout
+
+Full screen mode uses a two-column layout:
+
+### Left Sidebar
+- **Task Information**: Title, description, and metadata
+- **Development Toolbar**: Primary development actions
+- **TODOs**: Task checklist and progress tracking
+- **Relationships**: Subtasks and parent task links
+
+### Right Panel
+- **Tab Navigation**: Switch between Logs, Diffs, and Processes
+- **Content Area**: Active tab content with real-time updates
+- **Follow-up Section**: Additional context and actions
+
+## Core Features
+
+### Development Server
+
+Start and manage your project's development environment directly from the task interface.
+
+**Controls:**
+- **Dev** (▶️): Start the development server using your project's configured dev script
+- **Stop Dev** (⏹️): Terminate the running development server
+- **View Logs** (📄): Jump to process logs to monitor server output
+
+The development server runs in a git worktree environment and streams all output to the Processes tab. Click the logs button next to the dev server control to jump directly to the process logs for real-time monitoring.
+
+### Git Operations
+
+#### Rebase
+Keep your task branch up-to-date with the latest changes from the base branch.
+
+- **Automatic Detection**: The rebase button appears when your branch is behind the base branch
+- **Conflict Handling**: Any merge conflicts are displayed in the Diffs tab
+
+#### Merge
+Integrate your completed work back into the base branch.
+
+- **Availability**: Disabled when an open pull request exists
+- **Success Indication**: A "Merged!" notification confirms successful integration
+
+#### Push & Pull Request Management
+- **Create PR**: Opens pull request creation dialog for new branches
+- **Push to PR**: Updates existing pull request with latest changes
+- **Auto-detection**: Automatically detects existing PRs and adjusts button behavior
+
+### Task Management
+
+#### History & Attempts
+View and manage all task attempts from the full screen interface.
+
+- **History**: View all previous attempts for this task, review execution status and outcomes, and switch between different attempts to compare results
+- **New Attempt**: Create additional attempts when previous approaches didn't work as expected or when testing different implementation strategies
+
+
+For detailed information about when and why to create new attempts, see [Creating Task Attempts](/core-features/creating-task-attempts).
+
+
+#### Subtasks
+Break down complex tasks into manageable pieces.
+
+- **Create Subtask** (🔀): Opens task creation form with:
+ - Parent task automatically linked
+ - Initial base branch set to the current attempt's branch
+ - Subtasks link to specific task attempts, not tasks themselves
+
+
+Creating new task attempts affects existing subtasks, as they remain linked to their original parent attempt.
+
+
+Learn more in [Creating Subtasks](/core-features/subtasks).
+
+### Monitoring & Analysis
+
+#### Logs Tab
+The Logs tab provides real-time streaming of coding agent activities and reasoning. You can see the agent's thought process, actions being taken, and responses as tasks are executed. Process events from development servers, builds, and script execution are also logged here.
+
+
+
+
+
+#### Diffs Tab
+The Diffs tab provides a visual representation of all code changes made during task execution. It shows a git diff between your branch and the base branch, with syntax highlighting and language-aware code formatting. You can see a summary of added, modified, and deleted files with precise line-by-line change tracking and context.
+
+
+
+
+
+Learn more in [Reviewing Code Changes](/core-features/reviewing-code-changes).
+
+#### Processes Tab
+The Processes tab displays a timeline view of all running and completed processes. You can track the status of running, completed, failed, and stopped processes with their complete execution timeline. Click any process to view its specific output logs, and use the interactive controls to stop running processes directly from the interface.
+
+
+
+
+
+## Navigation & Controls
+
+### Keyboard Shortcuts
+- **Escape**: Exit full screen mode and return to sidebar view
+- **Tab Navigation**: Use browser tab controls to switch between Logs, Diffs, and Processes
+
+
+
+## Exiting Full Screen Mode
+
+- Click the **Minimize** button in the header
+- Press **Escape** key
+- Click the **×** button to close the task panel entirely
+- Navigate to a different task or project
+
+The interface gracefully transitions back to the compact sidebar view while preserving your work context.
+
+## Related Documentation
+
+- [Creating Task Attempts](/core-features/creating-task-attempts) - Learn about task attempt lifecycle
+- [Reviewing Code Changes](/core-features/reviewing-code-changes) - Deep dive into diff analysis
+- [Creating Tasks](/core-features/creating-tasks) - Task creation and management
+- [Agent Configurations](/configuration-customisation/agent-configurations) - Customise AI agent behaviour
diff --git a/docs/development.mdx b/docs/development.mdx
deleted file mode 100644
index ac633bad..00000000
--- a/docs/development.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: 'Development'
-description: 'Preview changes locally to update your docs'
----
-
-
- **Prerequisites**:
- - Node.js version 19 or higher
- - A docs repository with a `docs.json` file
-
-
-Follow these steps to install and run Mintlify on your operating system.
-
-
-
-
-```bash
-npm i -g mint
-```
-
-
-
-
-Navigate to your docs directory where your `docs.json` file is located, and run the following command:
-
-```bash
-mint dev
-```
-
-A local preview of your documentation will be available at `http://localhost:3000`.
-
-
-
-
-## Custom ports
-
-By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. For example, to run Mintlify on port 3333, use this command:
-
-```bash
-mint dev --port 3333
-```
-
-If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
-
-```md
-Port 3000 is already in use. Trying 3001 instead.
-```
-
-## Mintlify versions
-
-Please note that each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, please update the CLI:
-
-```bash
-npm mint update
-```
-
-## Validating links
-
-The CLI can assist with validating links in your documentation. To identify any broken links, use the following command:
-
-```bash
-mint broken-links
-```
-
-## Deployment
-
-If the deployment is successful, you should see the following:
-
-
-
-
-
-## Code formatting
-
-We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
-
-## Troubleshooting
-
-
-
-
- This may be due to an outdated version of node. Try the following:
- 1. Remove the currently-installed version of the CLI: `npm remove -g mint`
- 2. Upgrade to Node v19 or higher.
- 3. Reinstall the CLI: `npm i -g mint`
-
-
-
-
- Solution: Go to the root of your device and delete the `~/.mintlify` folder. Then run `mint dev` again.
-
-
-
-Curious about what changed in the latest CLI version? Check out the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions).
diff --git a/docs/docs.json b/docs/docs.json
index c6936ef3..346a1b21 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -3,6 +3,10 @@
"theme": "mint",
"name": "Vibe Kanban",
"description": "A kanban board for developers to track coding tasks with AI coding agents",
+ "banner": {
+ "content": "🎉 **Ultimate Agents Hackathon** - London, September 20th | £10k in prizes! [Register now](https://london.aitinkerers.org/p/ultimate-agents-hackathon-10k-total-prizes)",
+ "dismissible": true
+ },
"colors": {
"primary": "#000000",
"light": "#fefefe",
@@ -19,31 +23,35 @@
"groups": [
{
"group": "Getting started",
- "pages": ["index", "getting-started", "onboarding", "global-settings"]
+ "pages": ["index", "getting-started", "supported-coding-agents"]
},
{
- "group": "Supported Coding Agents",
+ "group": "Core Features",
"pages": [
- "supported-coding-agents",
- "supported-coding-agents/amp",
- "supported-coding-agents/claude-code",
- "supported-coding-agents/cursor-cli",
- "supported-coding-agents/ccr",
- "supported-coding-agents/codex",
- "supported-coding-agents/gemini-cli",
- "supported-coding-agents/sst-opencode",
- "supported-coding-agents/qwen-code"
+ "core-features/creating-projects",
+ "core-features/creating-tasks",
+ "core-features/subtasks",
+ "core-features/creating-task-attempts",
+ "core-features/reviewing-code-changes",
+ "core-features/task-details-full-screen"
]
},
{
- "group": "User Guide",
+ "group": "Configuration & Customisation",
"pages": [
- "user-guide/creating-projects",
- "user-guide/creating-tasks",
- "user-guide/creating-task-attempts",
- "user-guide/creating-task-templates",
- "user-guide/agent-configurations",
- "user-guide/vibe-kanban-mcp-server"
+ "configuration-customisation/global-settings",
+ "configuration-customisation/agent-configurations",
+ "configuration-customisation/creating-task-templates",
+ "configuration-customisation/keyboard-shortcuts"
+ ]
+ },
+ {
+ "group": "Integrations",
+ "pages": [
+ "integrations/github-integration",
+ "integrations/vscode-extension",
+ "integrations/mcp-server-configuration",
+ "integrations/vibe-kanban-mcp-server"
]
}
]
diff --git a/docs/essentials/code.mdx b/docs/essentials/code.mdx
deleted file mode 100644
index ae2abbfe..00000000
--- a/docs/essentials/code.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: 'Code blocks'
-description: 'Display inline code and code blocks'
-icon: 'code'
----
-
-## Inline code
-
-To denote a `word` or `phrase` as code, enclose it in backticks (`).
-
-```
-To denote a `word` or `phrase` as code, enclose it in backticks (`).
-```
-
-## Code blocks
-
-Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
-
-```java HelloWorld.java
-class HelloWorld {
- public static void main(String[] args) {
- System.out.println("Hello, World!");
- }
-}
-```
-
-````md
-```java HelloWorld.java
-class HelloWorld {
- public static void main(String[] args) {
- System.out.println("Hello, World!");
- }
-}
-```
-````
diff --git a/docs/essentials/images.mdx b/docs/essentials/images.mdx
deleted file mode 100644
index 1144eb2c..00000000
--- a/docs/essentials/images.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: 'Images and embeds'
-description: 'Add image, video, and other HTML elements'
-icon: 'image'
----
-
-
-
-## Image
-
-### Using Markdown
-
-The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
-
-```md
-
-```
-
-Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
-
-### Using embeds
-
-To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
-
-```html
-
-```
-
-## Embeds and HTML elements
-
-
-
-
-
-
-
-Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
-
-
-
-### iFrames
-
-Loads another HTML page within the document. Most commonly used for embedding videos.
-
-```html
-
-```
diff --git a/docs/essentials/markdown.mdx b/docs/essentials/markdown.mdx
deleted file mode 100644
index a45c1d56..00000000
--- a/docs/essentials/markdown.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
----
-title: 'Markdown syntax'
-description: 'Text, title, and styling in standard markdown'
-icon: 'text-size'
----
-
-## Titles
-
-Best used for section headers.
-
-```md
-## Titles
-```
-
-### Subtitles
-
-Best used for subsection headers.
-
-```md
-### Subtitles
-```
-
-
-
-Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
-
-
-
-## Text formatting
-
-We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
-
-| Style | How to write it | Result |
-| ------------- | ----------------- | --------------- |
-| Bold | `**bold**` | **bold** |
-| Italic | `_italic_` | _italic_ |
-| Strikethrough | `~strikethrough~` | ~strikethrough~ |
-
-You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
-
-You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
-
-| Text Size | How to write it | Result |
-| ----------- | ------------------------ | ---------------------- |
-| Superscript | `superscript` | superscript |
-| Subscript | `subscript` | subscript |
-
-## Linking to pages
-
-You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
-
-Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
-
-Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
-
-## Blockquotes
-
-### Singleline
-
-To create a blockquote, add a `>` in front of a paragraph.
-
-> Dorothy followed her through many of the beautiful rooms in her castle.
-
-```md
-> Dorothy followed her through many of the beautiful rooms in her castle.
-```
-
-### Multiline
-
-> Dorothy followed her through many of the beautiful rooms in her castle.
->
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
-
-```md
-> Dorothy followed her through many of the beautiful rooms in her castle.
->
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
-```
-
-### LaTeX
-
-Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
-
-8 x (vk x H1 - H2) = (0,1)
-
-```md
-8 x (vk x H1 - H2) = (0,1)
-```
diff --git a/docs/essentials/navigation.mdx b/docs/essentials/navigation.mdx
deleted file mode 100644
index 60adeff2..00000000
--- a/docs/essentials/navigation.mdx
+++ /dev/null
@@ -1,87 +0,0 @@
----
-title: 'Navigation'
-description: 'The navigation field in docs.json defines the pages that go in the navigation menu'
-icon: 'map'
----
-
-The navigation menu is the list of links on every website.
-
-You will likely update `docs.json` every time you add a new page. Pages do not show up automatically.
-
-## Navigation syntax
-
-Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
-
-
-
-```json Regular Navigation
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "pages": ["quickstart"]
- }
- ]
- }
- ]
-}
-```
-
-```json Nested Navigation
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "pages": [
- "quickstart",
- {
- "group": "Nested Reference Pages",
- "pages": ["nested-reference-page"]
- }
- ]
- }
- ]
- }
- ]
-}
-```
-
-
-
-## Folders
-
-Simply put your MDX files in folders and update the paths in `docs.json`.
-
-For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
-
-
-
-You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
-
-
-
-```json Navigation With Folder
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Group Name",
- "pages": ["your-folder/your-page"]
- }
- ]
- }
- ]
-}
-```
-
-## Hidden pages
-
-MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
diff --git a/docs/essentials/reusable-snippets.mdx b/docs/essentials/reusable-snippets.mdx
deleted file mode 100644
index 376e27bd..00000000
--- a/docs/essentials/reusable-snippets.mdx
+++ /dev/null
@@ -1,110 +0,0 @@
----
-title: "Reusable snippets"
-description: "Reusable, custom snippets to keep content in sync"
-icon: "recycle"
----
-
-import SnippetIntro from '/snippets/snippet-intro.mdx';
-
-
-
-## Creating a custom snippet
-
-**Pre-condition**: You must create your snippet file in the `snippets` directory.
-
-
- Any page in the `snippets` directory will be treated as a snippet and will not
- be rendered into a standalone page. If you want to create a standalone page
- from the snippet, import the snippet into another file and call it as a
- component.
-
-
-### Default export
-
-1. Add content to your snippet file that you want to re-use across multiple
- locations. Optionally, you can add variables that can be filled in via props
- when you import the snippet.
-
-```mdx snippets/my-snippet.mdx
-Hello world! This is my content I want to reuse across pages. My keyword of the
-day is {word}.
-```
-
-
- The content that you want to reuse must be inside the `snippets` directory in
- order for the import to work.
-
-
-2. Import the snippet into your destination file.
-
-```mdx destination-file.mdx
----
-title: My title
-description: My Description
----
-
-import MySnippet from '/snippets/path/to/my-snippet.mdx';
-
-## Header
-
-Lorem impsum dolor sit amet.
-
-
-```
-
-### Reusable variables
-
-1. Export a variable from your snippet file:
-
-```mdx snippets/path/to/custom-variables.mdx
-export const myName = 'my name';
-
-export const myObject = { fruit: 'strawberries' };
-```
-
-2. Import the snippet from your destination file and use the variable:
-
-```mdx destination-file.mdx
----
-title: My title
-description: My Description
----
-
-import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
-
-Hello, my name is {myName} and I like {myObject.fruit}.
-```
-
-### Reusable components
-
-1. Inside your snippet file, create a component that takes in props by exporting
- your component in the form of an arrow function.
-
-```mdx snippets/custom-component.mdx
-export const MyComponent = ({ title }) => (
-
-
{title}
-
... snippet content ...
-
-);
-```
-
-
- MDX does not compile inside the body of an arrow function. Stick to HTML
- syntax when you can or use a default export if you need to use MDX.
-
-
-2. Import the snippet into your destination file and pass in the props
-
-```mdx destination-file.mdx
----
-title: My title
-description: My Description
----
-
-import { MyComponent } from '/snippets/custom-component.mdx';
-
-Lorem ipsum dolor sit amet.
-
-
-```
diff --git a/docs/essentials/settings.mdx b/docs/essentials/settings.mdx
deleted file mode 100644
index 884de13a..00000000
--- a/docs/essentials/settings.mdx
+++ /dev/null
@@ -1,318 +0,0 @@
----
-title: 'Global Settings'
-description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file'
-icon: 'gear'
----
-
-Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below.
-
-## Properties
-
-
-Name of your project. Used for the global title.
-
-Example: `mintlify`
-
-
-
-
- An array of groups with all the pages within that group
-
-
- The name of the group.
-
- Example: `Settings`
-
-
-
- The relative paths to the markdown files that will serve as pages.
-
- Example: `["customization", "page"]`
-
-
-
-
-
-
-
- Path to logo image or object with path to "light" and "dark" mode logo images
-
-
- Path to the logo in light mode
-
-
- Path to the logo in dark mode
-
-
- Where clicking on the logo links you to
-
-
-
-
-
- Path to the favicon image
-
-
-
- Hex color codes for your global theme
-
-
- The primary color. Used for most often for highlighted content, section
- headers, accents, in light mode
-
-
- The primary color for dark mode. Used for most often for highlighted
- content, section headers, accents, in dark mode
-
-
- The primary color for important buttons
-
-
- The color of the background in both light and dark mode
-
-
- The hex color code of the background in light mode
-
-
- The hex color code of the background in dark mode
-
-
-
-
-
-
-
- Array of `name`s and `url`s of links you want to include in the topbar
-
-
- The name of the button.
-
- Example: `Contact us`
-
-
- The url once you click on the button. Example: `https://mintlify.com/docs`
-
-
-
-
-
-
-
-
- Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
-
-
- If `link`: What the button links to.
-
- If `github`: Link to the repository to load GitHub information from.
-
-
- Text inside the button. Only required if `type` is a `link`.
-
-
-
-
-
-
- Array of version names. Only use this if you want to show different versions
- of docs with a dropdown in the navigation bar.
-
-
-
- An array of the anchors, includes the `icon`, `color`, and `url`.
-
-
- The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
-
- Example: `comments`
-
-
- The name of the anchor label.
-
- Example: `Community`
-
-
- The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
-
-
- The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
-
-
- Used if you want to hide an anchor until the correct docs version is selected.
-
-
- Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
-
-
- Override the default configurations for the top-most anchor.
-
-
- The name of the top-most anchor
-
-
- Font Awesome icon.
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
-
- An array of navigational tabs.
-
-
- The name of the tab label.
-
-
- The start of the URL that marks what pages go in the tab. Generally, this
- is the name of the folder you put your pages in.
-
-
-
-
-
- Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
-
-
- The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
- options that the user can toggle.
-
-
-
-
-
- The authentication strategy used for all API endpoints.
-
-
- The name of the authentication parameter used in the API playground.
-
- If method is `basic`, the format should be `[usernameName]:[passwordName]`
-
-
- The default value that's designed to be a prefix for the authentication input field.
-
- E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
-
-
-
-
-
- Configurations for the API playground
-
-
-
- Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
-
- Learn more at the [playground guides](/api-playground/demo)
-
-
-
-
-
- Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
-
- This behavior will soon be enabled by default, at which point this field will be deprecated.
-
-
-
-
-
-
- A string or an array of strings of URL(s) or relative path(s) pointing to your
- OpenAPI file.
-
- Examples:
-
- ```json Absolute
- "openapi": "https://example.com/openapi.json"
- ```
- ```json Relative
- "openapi": "/openapi.json"
- ```
- ```json Multiple
- "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
- ```
-
-
-
-
-
- An object of social media accounts where the key:property pair represents the social media platform and the account url.
-
- Example:
- ```json
- {
- "x": "https://x.com/mintlify",
- "website": "https://mintlify.com"
- }
- ```
-
-
- One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
-
- Example: `x`
-
-
- The URL to the social platform.
-
- Example: `https://x.com/mintlify`
-
-
-
-
-
- Configurations to enable feedback buttons
-
-
-
- Enables a button to allow users to suggest edits via pull requests
-
-
- Enables a button to allow users to raise an issue about the documentation
-
-
-
-
-
- Customize the dark mode toggle.
-
-
- Set if you always want to show light or dark mode for new users. When not
- set, we default to the same mode as the user's operating system.
-
-
- Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
-
-
- ```json Only Dark Mode
- "modeToggle": {
- "default": "dark",
- "isHidden": true
- }
- ```
-
- ```json Only Light Mode
- "modeToggle": {
- "default": "light",
- "isHidden": true
- }
- ```
-
-
-
-
-
-
-
-
- A background image to be displayed behind every page. See example with
- [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
-
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
index e9b9b431..8bb13428 100644
--- a/docs/getting-started.mdx
+++ b/docs/getting-started.mdx
@@ -1,4 +1,8 @@
-# Install & Run Vibe Kanban
+---
+title: "Install & Run Vibe Kanban"
+description: "Complete installation guide for Vibe Kanban on macOS, Linux, and Windows"
+sidebarTitle: "Installation"
+---
## Supported Systems
@@ -8,30 +12,53 @@ We build and test Vibe Kanban on the following systems:
- Linux
- Windows
-## Pre-requisites
+## Prerequisites
-- Node.js
-- Coding agent authenticated
- - All supported coding agents can now be used via npx (no separate installation required)
- - You still need to authenticate with each coding agent outside of Vibe Kanban
- - You can find authentication instructions for each coding agent on their respective [websites](./supported-coding-agents).
+Before installing Vibe Kanban, ensure you have:
-## Running Vibe Kanban
+- **Node.js**: Latest LTS version recommended
+- **Coding agent authentication**: Authenticate with your preferred coding agents outside of Vibe Kanban
-1. Open a terminal and run:
+
+All supported coding agents can be used via npx without separate installation. You can find authentication instructions for each coding agent on their respective [websites](./supported-coding-agents).
+
-```
-npx vibe-kanban
-```
+## Installation & Setup
-2. [Complete the onboarding steps](/docs/getting-started/onboarding) in the application
+
+
+ Open a terminal and run:
-3. [Configure Global Settings](/docs/getting-started/global-settings) to personalize your experience
+ ```bash
+ npx vibe-kanban
+ ```
-4. [Create a project](/docs/user-guide/creating-projects)
+
+ The application will bind to a random free port, print the URL in the terminal, and automatically open in your default browser.
+
+
-5. [Create tasks](/docs/user-guide/creating-tasks)
+
+ Complete the setup dialogs to configure your coding agent and editor preferences. GitHub authentication is optional and can be configured later.
+
-6. Optional: [Set up MCP integration](/docs/user-guide/vibe-kanban-mcp-server) to streamline task creation with coding agents
+
+ You'll land on an empty Projects page. Click "Create your first project" to set up your initial project.
+
-A note on ports: By default the application will bind to a random free port, print the URL in the terminal and attempt to open the link in the default browser. If you would like to use a fixed port you can optionally specify the `PORT` environment variable, so to force Vibe Kanban to start on port 8080 you would run `PORT=8080 npx vibe-kanban`.
+
+ Start tracking your work by [creating tasks](/core-features/creating-tasks) within your project.
+
+
+
+ Connect to GitHub in [Settings](/configuration-customisation/global-settings) to enable branch management and pull request creation.
+
+
+
+ Streamline task creation with coding agents by [setting up MCP integration](/integrations/vibe-kanban-mcp-server).
+
+
+
+
+To use a fixed port, specify the `PORT` environment variable: `PORT=8080 npx vibe-kanban`
+
diff --git a/docs/global-settings.mdx b/docs/global-settings.mdx
deleted file mode 100644
index c004ccac..00000000
--- a/docs/global-settings.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
-# Global Settings
-
-You can configure application-wide settings via the **Settings** page. To access it, click the ⚙️ icon in the sidebar or select "Settings" from the top-right menu.
-
-
-
-## Themes
-
-Switch between light and dark themes to suit your preference.
-
-## Default Agent Configuration
-
-Choose the default agent and, if available, a variant. This profile is pre-selected when creating new task attempts and follow-ups.
-
-- Pick an agent (e.g., CLAUDE_CODE, GEMINI, CODEX)
-- If that agent has variants, pick one (e.g., DEFAULT, PLAN, ROUTER)
-- You can change this per attempt in the create attempt dialog
-
-## Editor Integration
-
-Configure integration with your preferred code editor (e.g., VS Code) for a seamless development workflow.
-
-## GitHub Integration
-
-Link your GitHub account by providing a Personal Access Token (PAT) and authenticating. This enables branch management, pull request creation, and status tracking directly from Vibe Kanban.
-
-## Notifications
-
-Toggle sound effects and push notifications to stay informed about task status changes.
-
-## Telemetry
-
-Enable or disable telemetry data collection to help improve Vibe Kanban.
-
-## Task Templates
-
-Manage global task templates to accelerate task creation across all projects. Templates allow you to define a default title and description that can be reused when adding new tasks.
-
-You can learn more about task templates on the [Task Templates](/docs/user-guide/creating-task-templates) page.
-
-## Agent Settings (Profiles & Variants)
-
-Define and customize agent variants under Settings → Agents. Variants let you maintain multiple configurations for the same agent (for example a CLAUDE_CODE "PLAN" variant). See the [Agent Profiles & Variants](/docs/user-guide/agent-configurations) guide for details and examples.
-
-## Safety & Disclaimers
-
-Manage acknowledgments and reset options for onboarding, safety disclaimers, and telemetry notices.
-
-- **Onboarding**: Reset the onboarding process to rerun the initial setup.
-- **Safety Disclaimer**: Reset or review the safety disclaimer prompt.
-- **Telemetry Notice**: Reset or review the telemetry data collection acknowledgment.
diff --git a/docs/images/add-line-comment.png b/docs/images/add-line-comment.png
new file mode 100644
index 00000000..e7325753
Binary files /dev/null and b/docs/images/add-line-comment.png differ
diff --git a/docs/images/checks-passed.png b/docs/images/checks-passed.png
deleted file mode 100644
index 3303c773..00000000
Binary files a/docs/images/checks-passed.png and /dev/null differ
diff --git a/docs/images/github-connect-settings.png b/docs/images/github-connect-settings.png
new file mode 100644
index 00000000..4297752c
Binary files /dev/null and b/docs/images/github-connect-settings.png differ
diff --git a/docs/images/github-device-code.png b/docs/images/github-device-code.png
new file mode 100644
index 00000000..f18009c3
Binary files /dev/null and b/docs/images/github-device-code.png differ
diff --git a/docs/images/hero-dark.png b/docs/images/hero-dark.png
deleted file mode 100644
index a61cbb12..00000000
Binary files a/docs/images/hero-dark.png and /dev/null differ
diff --git a/docs/images/hero-light.png b/docs/images/hero-light.png
deleted file mode 100644
index 68c712d6..00000000
Binary files a/docs/images/hero-light.png and /dev/null differ
diff --git a/docs/images/screenshot-agent-running-full.png b/docs/images/screenshot-agent-running-full.png
deleted file mode 100644
index 6078dd8d..00000000
Binary files a/docs/images/screenshot-agent-running-full.png and /dev/null differ
diff --git a/docs/images/screenshot-agent-running.png b/docs/images/screenshot-agent-running.png
deleted file mode 100644
index 072eb544..00000000
Binary files a/docs/images/screenshot-agent-running.png and /dev/null differ
diff --git a/docs/images/screenshot-create-project.png b/docs/images/screenshot-create-project.png
deleted file mode 100644
index 45ea47f1..00000000
Binary files a/docs/images/screenshot-create-project.png and /dev/null differ
diff --git a/docs/images/screenshot-create-subtask-button.png b/docs/images/screenshot-create-subtask-button.png
new file mode 100644
index 00000000..671e5a2d
Binary files /dev/null and b/docs/images/screenshot-create-subtask-button.png differ
diff --git a/docs/images/screenshot-create-task-attempt.png b/docs/images/screenshot-create-task-attempt.png
index 9f514de5..a4c7f5ee 100644
Binary files a/docs/images/screenshot-create-task-attempt.png and b/docs/images/screenshot-create-task-attempt.png differ
diff --git a/docs/images/screenshot-create-task-template-dropdown.png b/docs/images/screenshot-create-task-template-dropdown.png
index e38f1f29..da901013 100644
Binary files a/docs/images/screenshot-create-task-template-dropdown.png and b/docs/images/screenshot-create-task-template-dropdown.png differ
diff --git a/docs/images/screenshot-create-task.png b/docs/images/screenshot-create-task.png
index da8847a5..1f1648cd 100644
Binary files a/docs/images/screenshot-create-task.png and b/docs/images/screenshot-create-task.png differ
diff --git a/docs/images/screenshot-file-dropdown.png b/docs/images/screenshot-file-dropdown.png
deleted file mode 100644
index 17c9c404..00000000
Binary files a/docs/images/screenshot-file-dropdown.png and /dev/null differ
diff --git a/docs/images/screenshot-global-settings.png b/docs/images/screenshot-global-settings.png
deleted file mode 100644
index a6dff854..00000000
Binary files a/docs/images/screenshot-global-settings.png and /dev/null differ
diff --git a/docs/images/screenshot-global-task-templates.png b/docs/images/screenshot-global-task-templates.png
index a189eafc..1efde7cd 100644
Binary files a/docs/images/screenshot-global-task-templates.png and b/docs/images/screenshot-global-task-templates.png differ
diff --git a/docs/images/screenshot-mcp-servers.png b/docs/images/screenshot-mcp-servers.png
deleted file mode 100644
index 6dbdffa0..00000000
Binary files a/docs/images/screenshot-mcp-servers.png and /dev/null differ
diff --git a/docs/images/screenshot-onboarding.png b/docs/images/screenshot-onboarding.png
deleted file mode 100644
index e58c172f..00000000
Binary files a/docs/images/screenshot-onboarding.png and /dev/null differ
diff --git a/docs/images/screenshot-overview-confetti.png b/docs/images/screenshot-overview-confetti.png
deleted file mode 100644
index 6e10050f..00000000
Binary files a/docs/images/screenshot-overview-confetti.png and /dev/null differ
diff --git a/docs/images/screenshot-project-task-templates.png b/docs/images/screenshot-project-task-templates.png
index 17422a07..b0fe73d2 100644
Binary files a/docs/images/screenshot-project-task-templates.png and b/docs/images/screenshot-project-task-templates.png differ
diff --git a/docs/images/screenshot-setup-script-running.png b/docs/images/screenshot-setup-script-running.png
deleted file mode 100644
index 6b9fa694..00000000
Binary files a/docs/images/screenshot-setup-script-running.png and /dev/null differ
diff --git a/docs/images/screenshot-subtask-parent-info.png b/docs/images/screenshot-subtask-parent-info.png
new file mode 100644
index 00000000..04305e5d
Binary files /dev/null and b/docs/images/screenshot-subtask-parent-info.png differ
diff --git a/docs/images/screenshot-task-attempt-toolbar.png b/docs/images/screenshot-task-attempt-toolbar.png
deleted file mode 100644
index db719e5f..00000000
Binary files a/docs/images/screenshot-task-attempt-toolbar.png and /dev/null differ
diff --git a/docs/images/screenshot-task-with-subtasks.png b/docs/images/screenshot-task-with-subtasks.png
new file mode 100644
index 00000000..c55e8df1
Binary files /dev/null and b/docs/images/screenshot-task-with-subtasks.png differ
diff --git a/docs/images/task-attempt-push-button.png b/docs/images/task-attempt-push-button.png
new file mode 100644
index 00000000..42073a59
Binary files /dev/null and b/docs/images/task-attempt-push-button.png differ
diff --git a/docs/images/vibe-kanban-logo.svg b/docs/images/vibe-kanban-logo.svg
deleted file mode 100644
index 7f39f01f..00000000
--- a/docs/images/vibe-kanban-logo.svg
+++ /dev/null
@@ -1,294 +0,0 @@
-
-
\ No newline at end of file
diff --git a/docs/images/vk-create-pr.png b/docs/images/vk-create-pr.png
new file mode 100644
index 00000000..91de462c
Binary files /dev/null and b/docs/images/vk-create-pr.png differ
diff --git a/docs/images/vk-create-project.png b/docs/images/vk-create-project.png
new file mode 100644
index 00000000..07ed1f2c
Binary files /dev/null and b/docs/images/vk-create-project.png differ
diff --git a/docs/images/vk-diffs.png b/docs/images/vk-diffs.png
new file mode 100644
index 00000000..e65bab2b
Binary files /dev/null and b/docs/images/vk-diffs.png differ
diff --git a/docs/images/vk-logs.png b/docs/images/vk-logs.png
new file mode 100644
index 00000000..741627b3
Binary files /dev/null and b/docs/images/vk-logs.png differ
diff --git a/docs/images/vk-mcp-server-config.jpeg b/docs/images/vk-mcp-server-config.jpeg
new file mode 100644
index 00000000..03257328
Binary files /dev/null and b/docs/images/vk-mcp-server-config.jpeg differ
diff --git a/docs/images/vk-popular-mcp-servers.png b/docs/images/vk-popular-mcp-servers.png
new file mode 100644
index 00000000..94256b30
Binary files /dev/null and b/docs/images/vk-popular-mcp-servers.png differ
diff --git a/docs/images/vk-processes.png b/docs/images/vk-processes.png
new file mode 100644
index 00000000..0fe6097c
Binary files /dev/null and b/docs/images/vk-processes.png differ
diff --git a/docs/images/vk-raycast-mcp-part-1.png b/docs/images/vk-raycast-mcp-part-1.png
new file mode 100644
index 00000000..ed0dd18a
Binary files /dev/null and b/docs/images/vk-raycast-mcp-part-1.png differ
diff --git a/docs/images/vk-raycast-mcp-part-2.png b/docs/images/vk-raycast-mcp-part-2.png
new file mode 100644
index 00000000..dcf0e168
Binary files /dev/null and b/docs/images/vk-raycast-mcp-part-2.png differ
diff --git a/docs/images/vk-settings.png b/docs/images/vk-settings.png
new file mode 100644
index 00000000..09b214b7
Binary files /dev/null and b/docs/images/vk-settings.png differ
diff --git a/docs/images/vk-task-detail.jpeg b/docs/images/vk-task-detail.jpeg
new file mode 100644
index 00000000..28c1d280
Binary files /dev/null and b/docs/images/vk-task-detail.jpeg differ
diff --git a/docs/index.mdx b/docs/index.mdx
index e71a485a..37f83fa1 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -1,20 +1,17 @@
---
title: "Vibe Kanban Documentation"
-description: "Welcome to Vibe Kanban - the kanban board for developers working with AI coding agents"
+description: "A specialised kanban board designed for developers who want to track and manage their coding tasks while working with AI coding agents. It provides seamless integration with various coding agents and helps you organise your development workflow efficiently."
+sidebarTitle: "Home"
---
-# Welcome to Vibe Kanban
-
-Vibe Kanban is a specialized kanban board designed for developers who want to track and manage their coding tasks while working with AI coding agents. It provides seamless integration with various coding agents and helps you organize your development workflow efficiently.
-
## What is Vibe Kanban?
Vibe Kanban transforms how developers work with AI coding agents by providing:
-- **Task Management**: Create, organize, and track coding tasks on an intuitive kanban board
+- **Task Management**: Create, organise, and track coding tasks on an intuitive kanban board
- **AI Agent Integration**: Works with popular coding agents like Amp, Claude Code, Cursor CLI, and more
- **Git Integration**: Automatic branch management and pull request tracking
-- **Workspace Management**: Organize multiple projects with custom setup scripts
+- **Workspace Management**: Organise multiple projects with custom setup scripts
- **Real-time Progress Tracking**: Monitor task attempts and coding agent execution
## Key Features
@@ -25,15 +22,15 @@ Vibe Kanban transforms how developers work with AI coding agents by providing:
- Organize your repositories with custom setup scripts and development workflows
+ Organise your repositories with custom setup scripts and development workflows
Create and manage coding tasks with templates, descriptions, and progress tracking
-
- Automatic branch creation, PR management, and GitHub status synchronization
+
+ Automatic branch creation, PR management, and GitHub status synchronisation
@@ -52,7 +49,7 @@ Ready to get started? Follow our getting started guide to install and configure
Complete guides for creating projects, tasks, and working with coding agents
-
+
Configure themes, default agents, GitHub integration, and more
diff --git a/docs/integrations/github-integration.mdx b/docs/integrations/github-integration.mdx
new file mode 100644
index 00000000..81259257
--- /dev/null
+++ b/docs/integrations/github-integration.mdx
@@ -0,0 +1,86 @@
+---
+title: "GitHub Integration"
+description: "Connect to GitHub to unlock seamless branch management and pull request workflows directly from your kanban board"
+---
+
+Connect your GitHub account to push commits and create pull requests directly from task attempts.
+
+## See It In Action
+
+### Pull Request Creation Dialog
+
+
+
+
+
+When you're ready to create a PR, get a streamlined dialog that:
+- Pre-fills title and description from your task details
+- Lets you select the target branch (defaults to main/master)
+- Validates that your branch is ready to go
+- Provides direct links to your new pull request
+
+### Smart Push/PR Button
+
+
+
+
+
+Each task attempt gets a smart button that adapts to your current state:
+- **"Create PR"** when ready to share your work
+- **"Push X commits"** when you have changes to upload
+- **"Push to PR"** when updating an existing pull request
+- **"Pushed!"** confirmation after successful operations
+
+
+Each task attempt automatically creates an isolated git worktree, so you can work on multiple features simultaneously without conflicts.
+
+
+## Getting Started
+
+### Connect Your GitHub Account
+
+
+
+
+
+Click **Connect GitHub Account** in General Settings to authenticate with GitHub using device flow authentication.
+
+
+
+
+
+The authentication process is simple:
+1. Click **Sign in with GitHub**
+2. Visit the provided GitHub URL in your browser
+3. Enter the device code shown in the dialog
+4. Authorize Vibe Kanban in your browser
+5. Return to complete the setup
+
+**Required Permissions**: Vibe Kanban needs access to your repositories (`repo`), basic profile info (`read:user`), and email address (`user:email`) for Git commits.
+
+
+If you encounter permission issues when creating pull requests, you'll be prompted to provide a Personal Access Token as a fallback authentication method.
+
+
+### Start Working with GitHub
+
+
+
+[Create projects](/core-features/creating-projects) from existing Git repositories to enable GitHub features.
+
+
+
+[Create task attempts](/core-features/creating-task-attempts) to start developing in isolated branches.
+
+
+
+Use the dynamic push/PR button in task attempts to share your work on GitHub.
+
+
+
+## Next Steps
+
+With GitHub connected, you can:
+- [Learn about creating projects](/core-features/creating-projects)
+- [Set up task attempts for feature development](/core-features/creating-task-attempts)
+- [Review code changes before committing](/core-features/reviewing-code-changes)
diff --git a/docs/integrations/mcp-server-configuration.mdx b/docs/integrations/mcp-server-configuration.mdx
new file mode 100644
index 00000000..5b908b74
--- /dev/null
+++ b/docs/integrations/mcp-server-configuration.mdx
@@ -0,0 +1,89 @@
+---
+title: "Connecting MCP Servers"
+description: "Configure MCP (Model Context Protocol) servers to enhance your coding agents within Vibe Kanban with additional tools and capabilities."
+---
+
+
+
+This page covers configuring MCP servers **within** Vibe Kanban for your coding agents. For connecting external MCP clients to Vibe Kanban's MCP server, see the [Vibe Kanban MCP Server](/integrations/vibe-kanban-mcp-server) guide.
+
+
+## Overview
+
+MCP servers provide additional functionality to coding agents through standardized protocols. You can configure different MCP servers for each coding agent in Vibe Kanban, giving them access to specialized tools like browser automation, access to remote logs, error tracking via Sentry, or documentation from Notion.
+
+## Accessing MCP Server Configuration
+
+1. Navigate to **Settings** in the Vibe Kanban interface
+2. Click on **MCP Servers** in the settings menu
+3. Select the coding agent you want to configure MCP servers for
+
+
+
+
+
+## Popular MCP Servers
+
+Vibe Kanban provides one-click installation for popular MCP servers.
+
+
+
+
+
+## Adding Custom MCP Servers
+
+You can also add your own MCP servers by configuring them manually:
+
+
+
+Choose the coding agent you want to configure MCP servers for from the MCP Servers settings page.
+
+
+
+In the Server Configuration JSON field displayed in the UI, add your custom MCP server configuration. The JSON will show the current configuration for the selected agent, and you can modify it to include additional servers.
+
+Example addition:
+```json
+{
+ "mcpServers": {
+ "existing_server": {
+ "command": "npx",
+ "args": ["-y", "some-existing-server"]
+ },
+ "my_custom_server": {
+ "command": "node",
+ "args": ["/path/to/my-server.js"]
+ }
+ }
+}
+```
+
+
+
+After updating the JSON configuration:
+
+1. Click "Save Settings" to apply changes
+2. Test the configuration by using the agent with MCP functionality
+3. Check agent logs for any connection issues
+
+
+These changes update the global configuration file of the coding agent and will persist even if you stop using Vibe Kanban.
+
+
+
+
+## Best Practices
+
+
+**Server Selection**: Choose MCP servers that complement your coding agent's primary function. For example, use Playwright for agents focused on web development.
+
+
+
+**Limit MCP Servers**: Avoid adding too many MCP servers to a single coding agent. Too many servers and tools will degrade the effectiveness of coding agents by overwhelming them with options.
+
+
+## Next Steps
+
+- Explore the [Agent Configurations](/configuration-customisation/agent-configurations) guide for advanced agent setup
+- Learn about [Creating Tasks](/core-features/creating-tasks) with enhanced MCP capabilities
+- Check out [Supported Coding Agents](/supported-coding-agents) for agent-specific features
diff --git a/docs/integrations/vibe-kanban-mcp-server.mdx b/docs/integrations/vibe-kanban-mcp-server.mdx
new file mode 100644
index 00000000..32b73c5d
--- /dev/null
+++ b/docs/integrations/vibe-kanban-mcp-server.mdx
@@ -0,0 +1,115 @@
+---
+title: "Vibe Kanban MCP Server"
+description: "Configure the Vibe Kanban MCP server"
+---
+
+Vibe Kanban exposes a local MCP (Model Context Protocol) server, allowing you to manage projects and tasks from external MCP clients like Claude Desktop, Raycast, or even coding agents running within Vibe Kanban itself.
+
+
+This page covers connecting **external MCP clients** to Vibe Kanban's MCP server. For configuring MCP servers **within** Vibe Kanban for your coding agents, see the [MCP Server Configuration](/integrations/mcp-server-configuration) guide.
+
+
+
+Vibe Kanban's MCP server is **local-only** - it runs on your computer and can only be accessed by applications installed locally. It cannot be accessed via publicly accessible URLs.
+
+
+
+
+## Setting Up MCP Integration
+
+### Option 1: Using the Web Interface
+
+This works if you're adding the Vibe Kanban MCP server to any [supported coding agent](/supported-coding-agents) **within** Vibe Kanban.
+
+1. In Vibe Kanban Settings, navigate to the "MCP Servers" page
+2. In the "Popular servers" section, click on the Vibe Kanban card
+3. Click the `Save Settings` button
+
+
+
+
+
+### Option 2: Manual Configuration
+
+You can manually add the MCP server to your coding agent's configuration. Add the following configuration to your agent's MCP servers configuration:
+
+```json
+{
+ "mcpServers": {
+ "vibe_kanban": {
+ "command": "npx",
+ "args": ["-y", "vibe-kanban", "--mcp"]
+ }
+ }
+}
+```
+
+## Using MCP with Coding Agents
+
+Once you have the MCP server configured, you can leverage it to streamline your project planning workflow:
+
+1. **Plan Your Work**: Describe a large feature or project to your coding agent
+2. **Request Task Creation**: At the end of your task description, simply add "then turn this plan into tasks"
+3. **Automatic Task Generation**: Your coding agent will use the Vibe Kanban MCP server to automatically create structured tasks in your project
+
+## Example Usage
+
+### External Coding Agents
+
+```
+I need to build a user authentication system with the following features:
+- User registration with email validation
+- Login/logout functionality
+- Password reset capability
+- Session management
+- Protected routes
+
+Then turn this plan into tasks.
+```
+
+The coding agent will break this down into individual tasks and add them to your Vibe Kanban project automatically.
+
+### Internal Coding Agents (Within Vibe Kanban)
+
+A powerful workflow involves using coding agents within Vibe Kanban that are also connected to the Vibe Kanban MCP server:
+
+1. **Create a Planning Task**: Create a task in "plan mode" within Vibe Kanban
+2. **Explore and Plan**: The coding agent explores the codebase and develops a comprehensive plan
+3. **Generate Sub-Tasks**: Ask the coding agent to "create a series of individual tasks for this plan"
+4. **Automatic Population**: The agent uses the MCP server to populate individual tasks directly in the Vibe Kanban interface
+
+This creates a seamless workflow where high-level planning automatically generates actionable tasks in your project board.
+
+## Installation Instructions for MCP Clients
+
+### Raycast Example
+
+Raycast is a popular MCP client that can connect to Vibe Kanban's MCP server. Here's how to configure it:
+
+For complete Raycast MCP configuration details, see the [official Raycast MCP documentation](https://manual.raycast.com/model-context-protocol).
+
+
+
+
+
+
+
+Configure the Vibe Kanban MCP server in Raycast by adding the server details.
+
+
+
+
+
+
+
+Once configured, you'll see the Vibe Kanban MCP server listed and ready to use in Raycast.
+
+
+
+
+Similar configuration steps apply to other MCP clients like Claude Desktop, VS Code with MCP extensions, or any custom MCP client implementations.
+
diff --git a/docs/integrations/vscode-extension.mdx b/docs/integrations/vscode-extension.mdx
new file mode 100644
index 00000000..158e59cf
--- /dev/null
+++ b/docs/integrations/vscode-extension.mdx
@@ -0,0 +1,163 @@
+---
+title: "VSCode Extension Integration"
+description: "Complete guide to using the Vibe Kanban extension with VSCode, Cursor, and Windsurf"
+---
+
+The Vibe Kanban VSCode extension brings task management directly into your IDE, providing seamless integration with logs, diffs, and process monitoring. This extension works with VSCode and popular forks including Cursor and Windsurf.
+
+
+
+## Installation
+
+
+
+Install directly from the Visual Studio Code Marketplace:
+
+
+ Install the official Vibe Kanban extension for VSCode
+
+
+Alternatively, search for the extension ID in VSCode:
+1. Open VSCode
+2. Press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS) to open Extensions
+3. Search for `@id:bloop.vibe-kanban`
+4. Click **Install**
+
+
+
+For Cursor, use the Open VSX Registry:
+
+
+ Install from Open VSX for Cursor compatibility
+
+
+
+Since deeplinking from Open VSX doesn't work reliably in Cursor, the easiest installation method is searching by extension ID within the IDE.
+
+
+**Installation Steps**:
+1. Open Cursor
+2. Open the Extensions panel
+3. Search for `@id:bloop.vibe-kanban`
+4. Install the extension
+
+
+
+For Windsurf, use the Open VSX Registry:
+
+
+ Install from Open VSX for Windsurf compatibility
+
+
+
+Since deeplinking from Open VSX doesn't work reliably in Windsurf, the easiest installation method is searching by extension ID within the IDE.
+
+
+**Installation Steps**:
+1. Open Windsurf
+2. Open the Extensions panel
+3. Search for `@id:bloop.vibe-kanban`
+4. Install the extension
+
+
+
+## Features
+
+The extension provides an integrated workspace view with three main components:
+
+### Logs View
+- List of task attempts for the current task
+- Agent steps performed in each task attempt
+
+### Diffs View
+- Side-by-side comparison of code changes
+- Inline commenting and review capabilities
+
+### Processes View
+- Monitor running task processes
+- Process status indicators (running, completed, failed)
+
+### Task Management
+- **Task Iteration**: Continue iterating on the current ongoing task
+- **Status Updates**: Real-time task status synchronization
+
+## Usage Workflow
+
+
+
+ Navigate to your project's kanban board and create or select an existing task.
+
+
+
+ Click on the task to open its detailed view, then switch to full screen mode for better visibility.
+
+
+
+ Click the **"Open in VSCode"**, **"Open in Cursor"**, or **"Open in Windsurf"** button depending on your preferred IDE.
+
+
+ The button text will reflect your editor choice configured in Vibe Kanban settings.
+
+
+
+
+ Your IDE will open in the task's dedicated worktree with the extension UI populated with:
+ - Current task context
+ - Real-time logs
+ - Code diffs
+ - Process monitoring
+
+
+
+## Troubleshooting
+
+### Empty Extension UI
+
+**Problem**: The extension UI appears empty or shows no task information.
+
+**Solution**: Ensure you're working within a worktree created by a Vibe Kanban task.
+
+
+The extension can only display task information when VSCode is opened in a directory that corresponds to an active Vibe Kanban task worktree.
+
+
+**Steps to resolve**:
+1. Verify you opened VSCode through the "Open in [IDE]" button from a Vibe Kanban task
+2. Check that you're in the correct directory/worktree
+3. If the issue persists, restart your IDE and try the workflow again
+
+### Extension Not Loading
+
+**Problem**: The Vibe Kanban extension doesn't appear in your IDE.
+
+**Solutions**:
+- Verify the extension is installed by searching `@id:bloop.vibe-kanban` in Extensions
+- Restart your IDE after installation
+- Check that you're using a compatible IDE version
+- For Cursor/Windsurf users, ensure you installed from Open VSX Registry
+
+## Best Practices
+
+
+**Workflow Optimization**: Always start tasks from the Vibe Kanban web interface before opening in your IDE to ensure proper context and worktree setup.
+
+
+
+**Performance**: Close unused IDE windows to reduce resource usage.
+
+
+## Supported IDEs
+
+| IDE | Status | Installation Method |
+|-----|--------|-------------------|
+| **VSCode** | ✅ Fully Supported | VSCode Marketplace |
+| **Cursor** | ✅ Fully Supported | Open VSX Registry |
+| **Windsurf** | ✅ Fully Supported | Open VSX Registry |
+
+
+The extension is designed to work with any VSCode-compatible editor. If you're using a different VSCode fork, try installing from Open VSX Registry using the extension ID `bloop.vibe-kanban`.
+
diff --git a/docs/onboarding.mdx b/docs/onboarding.mdx
deleted file mode 100644
index 9de252eb..00000000
--- a/docs/onboarding.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
-# Onboarding
-
-When you first run Vibe Kanban (`npx vibe-kanban`), you'll be guided through an onboarding process to configure the application for your workflow. During onboarding, you will:
-
-- Choose your default agent configuration (agent and optional variant)
-- Authenticate with GitHub for branch management and PR tracking
-- Set up your initial workspace directory
-
-
-
-Once onboarding is complete, you'll be ready to create your first project and start tracking tasks.
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
deleted file mode 100644
index c711458b..00000000
--- a/docs/quickstart.mdx
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: "Quickstart"
-description: "Start building awesome documentation in minutes"
----
-
-## Get started in three steps
-
-Get your documentation site running locally and make your first customization.
-
-### Step 1: Set up your local environment
-
-
-
- During the onboarding process, you created a GitHub repository with your docs content if you didn't already have one. You can find a link to this repository in your [dashboard](https://dashboard.mintlify.com).
-
- To clone the repository locally so that you can make and preview changes to your docs, follow the [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) guide in the GitHub docs.
-
-
- 1. Install the Mintlify CLI: `npm i -g mint`
- 2. Navigate to your docs directory and run: `mint dev`
- 3. Open `http://localhost:3000` to see your docs live!
-
- Your preview updates automatically as you edit files.
-
-
-
-### Step 2: Deploy your changes
-
-
-
- Install the Mintlify GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app).
-
- Our GitHub app automatically deploys your changes to your docs site, so you don't need to manage deployments yourself.
-
-
- For a first change, let's update the name and colors of your docs site.
-
- 1. Open `docs.json` in your editor.
- 2. Change the `"name"` field to your project name.
- 3. Update the `"colors"` to match your brand.
- 4. Save and see your changes instantly at `http://localhost:3000`.
-
- Try changing the primary color to see an immediate difference!
-
-
-
-### Step 3: Go live
-
-
- 1. Commit and push your changes.
- 2. Your docs will update and be live in moments!
-
-
-## Next steps
-
-Now that you have your docs running, explore these key features:
-
-
-
-
- Learn MDX syntax and start writing your documentation.
-
-
-
- Make your docs match your brand perfectly.
-
-
-
- Include syntax-highlighted code blocks.
-
-
-
- Auto-generate API docs from OpenAPI specs.
-
-
-
-
-
- **Need help?** See our [full documentation](https://mintlify.com/docs) or join our [community](https://mintlify.com/community).
-
diff --git a/docs/snippets/snippet-intro.mdx b/docs/snippets/snippet-intro.mdx
deleted file mode 100644
index e20fbb6f..00000000
--- a/docs/snippets/snippet-intro.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
-One of the core principles of software development is DRY (Don't Repeat
-Yourself). This is a principle that applies to documentation as
-well. If you find yourself repeating the same content in multiple places, you
-should consider creating a custom snippet to keep your content in sync.
diff --git a/docs/supported-coding-agents.mdx b/docs/supported-coding-agents.mdx
index af1f7946..234d9722 100644
--- a/docs/supported-coding-agents.mdx
+++ b/docs/supported-coding-agents.mdx
@@ -1,14 +1,178 @@
-# Supported Coding Agents
+---
+title: "Supported Coding Agents"
+description: "Complete guide to all coding agents supported by Vibe Kanban, including installation and authentication instructions"
+---
Vibe Kanban integrates with a variety of coding agents. These agents are available via `npx` and can be selected when creating task attempts.
-| Agent | Documentation |
-|--------------------------------------|-----------------------------------|
-| [Amp](/docs/supported-coding-agents/amp) | Amp code completion |
-| [Claude Code](/docs/supported-coding-agents/claude-code) | Anthropic's Claude Code |
-| [Cursor CLI](/docs/supported-coding-agents/cursor-cli) | Cursor's command-line agent |
-| [CCR (Claude Code Router)](/docs/supported-coding-agents/ccr) | Orchestrate multiple Claude Code |
-| [Codex](/docs/supported-coding-agents/codex) | OpenAI Codex integration |
-| [Gemini CLI](/docs/supported-coding-agents/gemini-cli) | Google Gemini CLI |
-| [SST OpenCode](/docs/supported-coding-agents/sst-opencode) | SST's OpenCode |
-| [Qwen Code](/docs/supported-coding-agents/qwen-code) | Qwen code-focused assistant |
+
+
+
+**Amp code completion agent**
+
+## Installation
+Amp is now available via npx - no separate installation required!
+
+## Authentication
+You need to authenticate with Amp outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Amp Owner's Manual](https://ampcode.com/manual#install).
+
+
+
+**Anthropic's Claude Code**
+
+## Installation
+Claude Code is now available via npx - no separate installation required!
+
+## Authentication
+You need to authenticate with Claude Code outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Claude Code GitHub page](https://github.com/anthropics/claude-code).
+
+
+
+**Cursor's command-line agent**
+
+## Installation
+Install Cursor CLI using the official guide: https://docs.cursor.com/en/cli/installation. On most systems you can run `curl https://cursor.com/install -fsS | bash`, then verify with `cursor-agent --version`.
+
+## Authentication
+Sign in with `cursor-agent login` (opens a browser). You can also set the `CURSOR_API_KEY=...` environment variable. Full instructions: https://docs.cursor.com/en/cli/reference/authentication
+
+
+
+**Orchestrate multiple Claude Code models**
+
+CCR (Claude Code Router) lets you route coding prompts across different LLM providers and models, and select specialised models for specific tasks like long context, background work, or image understanding.
+
+## Installation
+CCR is available via `npx` – no separate installation required.
+
+```bash
+npx -y @musistudio/claude-code-router ui
+```
+
+This launches the CCR local UI where you configure providers and models.
+
+## Authentication
+Authenticate and configure CCR outside of Vibe Kanban. Follow the instructions on the CCR GitHub repo:
+
+- GitHub: https://github.com/musistudio/claude-code-router
+
+You'll add providers, set API keys, and register model names in the CCR UI or via CCR's JSON configuration (see the CCR repo for the schema and file location).
+
+## Configure CCR (Providers and Models)
+
+Configure CCR either via the UI or JSON config.
+
+In the CCR UI (`npx -y @musistudio/claude-code-router ui`):
+
+1) Add providers
+- Choose a provider (e.g., `openrouter`, `deepseek`, etc.).
+- Enter the required API key(s) and settings for that provider.
+
+2) Add models
+- For each provider, register the model identifier (e.g., `moonshotai/kimi-k2-0905`, `deepseek-chat`).
+- CCR supports configuring different models for specific cases:
+ - `default`: general coding
+ - `background`: lightweight/background operations
+ - `think`: models that support "thinking" modes
+ - `longContext`: very long inputs/files
+ - `webSearch`: models that support web/tool use
+ - `image`: models with vision capabilities
+
+Note: not all models support web search, thinking, or images. Choose models accordingly in the CCR UI.
+
+### Configure via JSON (optional)
+CCR can also be configured via its JSON configuration file. Refer to the CCR GitHub documentation for the exact schema, keys, and file location. Define providers (with API keys) and map the model cases (`default`, `background`, `think`, `longContext`, `webSearch`, `image`) to specific provider/model pairs.
+
+### Example: OpenRouter provider configured in CCR UI
+
+
+
+
+
+### Example: CCR model mapping (default/background/think/etc.)
+
+
+
+
+
+## Configure Vibe Kanban
+
+Vibe Kanban does not ship a default configuration for CCR. Add configurations to the existing Claude Code agent:
+
+1) Open the "Coding Agent Configurations" page.
+2) Add a new configuration for the Claude Code agent (or edit an existing one).
+3) Enable the `claude_code_router` checkbox.
+4) Optionally set a model string to target a specific CCR provider/model.
+
+See the [Agent Profiles & Variants](/configuration-customisation/agent-configurations) guide for managing agent configurations.
+
+Model string format: `,`
+
+Examples:
+```text
+openrouter,moonshotai/kimi-k2-0905
+deepseek,deepseek-chat
+```
+
+Tips:
+- Create multiple configurations if you want easy switching between different models.
+- Leave the model string empty if you want CCR to use its own routing based on your CCR UI configuration (e.g., its `default`/`longContext`/etc. mappings).
+
+### Example: Claude Code agent configuration in Vibe Kanban
+
+
+
+
+
+## Using CCR in Vibe Kanban
+
+When creating a Task Attempt, select the coding agent and configuration: choose the Claude Code agent, then pick one of your CCR-enabled configurations.
+
+## Troubleshooting
+
+- Authentication errors: verify your API keys/provider settings in CCR (via UI or JSON config).
+- Model not found: confirm the model identifier is correct for the chosen provider.
+- Missing features (webSearch/think/image): switch to a model that supports the capability and update your CCR mapping (via UI or JSON config).
+
+
+
+**OpenAI Codex integration**
+
+## Installation
+OpenAI Codex is now available via `npx` - no separate installation required!
+
+## Authentication
+You need to configure your OpenAI API credentials before using Codex. Please set the `OPENAI_API_KEY` environment variable. For more details, see the [OpenAI documentation](https://platform.openai.com/docs/guides/code).
+
+
+
+**Google Gemini CLI**
+
+## Installation
+Gemini CLI is now available via npx - no separate installation required!
+
+## Authentication
+You need to authenticate with Gemini CLI outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Gemini CLI GitHub page](https://github.com/google-gemini/gemini-cli).
+
+
+
+**SST's OpenCode**
+
+## Installation
+SST OpenCode is now available via `npx` - no separate installation required!
+
+## Authentication
+You need to authenticate with SST OpenCode outside of Vibe Kanban before using it. Please follow the authentication instructions on the [SST OpenCode GitHub page](https://github.com/sst/opencode).
+
+
+
+**Qwen code-focused assistant**
+
+## Installation
+Qwen Code is available via npx - no separate installation required!
+
+## Authentication
+You need to authenticate with Qwen outside of Vibe Kanban before using it. Please follow the authentication instructions in the official Qwen documentation: https://github.com/QwenLM/qwen-code
+
+
+
diff --git a/docs/supported-coding-agents/amp.mdx b/docs/supported-coding-agents/amp.mdx
deleted file mode 100644
index 77f4111a..00000000
--- a/docs/supported-coding-agents/amp.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-# Amp
-
-## Installation
-
-Amp is now available via npx - no separate installation required!
-
-## Authentication
-
-You need to authenticate with Amp outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Amp Owner's Manual](https://ampcode.com/manual#install).
diff --git a/docs/supported-coding-agents/ccr.mdx b/docs/supported-coding-agents/ccr.mdx
deleted file mode 100644
index defef284..00000000
--- a/docs/supported-coding-agents/ccr.mdx
+++ /dev/null
@@ -1,93 +0,0 @@
-# CCR (Claude Code Router)
-
-CCR (Claude Code Router) lets you route coding prompts across different LLM providers and models, and select specialized models for specific tasks like long context, background work, or image understanding.
-
-## Installation
-
-CCR is available via `npx` – no separate installation required.
-
-```bash
-npx -y @musistudio/claude-code-router ui
-```
-
-This launches the CCR local UI where you configure providers and models.
-
-## Authentication
-
-Authenticate and configure CCR outside of Vibe Kanban. Follow the instructions on the CCR GitHub repo:
-
-- GitHub: https://github.com/musistudio/claude-code-router
-
-You’ll add providers, set API keys, and register model names in the CCR UI or via CCR’s JSON configuration (see the CCR repo for the schema and file location).
-
-## Configure CCR (Providers and Models)
-
-Configure CCR either via the UI or JSON config.
-
-In the CCR UI (`npx -y @musistudio/claude-code-router ui`):
-
-1) Add providers
-- Choose a provider (e.g., `openrouter`, `deepseek`, etc.).
-- Enter the required API key(s) and settings for that provider.
-
-2) Add models
-- For each provider, register the model identifier (e.g., `moonshotai/kimi-k2-0905`, `deepseek-chat`).
-- CCR supports configuring different models for specific cases:
- - `default`: general coding
- - `background`: lightweight/background operations
- - `think`: models that support “thinking” modes
- - `longContext`: very long inputs/files
- - `webSearch`: models that support web/tool use
- - `image`: models with vision capabilities
-
-Note: not all models support web search, thinking, or images. Choose models accordingly in the CCR UI.
-
-### Configure via JSON (optional)
-
-CCR can also be configured via its JSON configuration file. Refer to the CCR GitHub documentation for the exact schema, keys, and file location. Define providers (with API keys) and map the model cases (`default`, `background`, `think`, `longContext`, `webSearch`, `image`) to specific provider/model pairs.
-
-### Example: OpenRouter provider configured in CCR UI
-
-
-
-### Example: CCR model mapping (default/background/think/etc.)
-
-
-
-## Configure Vibe Kanban
-
-Vibe Kanban does not ship a default configuration for CCR. Add configurations to the existing Claude Code agent:
-
-1) Open the “Coding Agent Configurations” page.
-2) Add a new configuration for the Claude Code agent (or edit an existing one).
-3) Enable the `claude_code_router` checkbox.
-4) Optionally set a model string to target a specific CCR provider/model.
-
-See the [Agent Profiles & Variants](/docs/user-guide/agent-configurations) guide for managing agent configurations.
-
-Model string format: `,`
-
-Examples:
-
-```text
-openrouter,moonshotai/kimi-k2-0905
-deepseek,deepseek-chat
-```
-
-Tips:
-- Create multiple configurations if you want easy switching between different models.
-- Leave the model string empty if you want CCR to use its own routing based on your CCR UI configuration (e.g., its `default`/`longContext`/etc. mappings).
-
-### Example: Claude Code agent configuration in Vibe Kanban
-
-
-
-## Using CCR in Vibe Kanban
-
-When creating a Task Attempt, select the coding agent and configuration: choose the Claude Code agent, then pick one of your CCR-enabled configurations.
-
-## Troubleshooting
-
-- Authentication errors: verify your API keys/provider settings in CCR (via UI or JSON config).
-- Model not found: confirm the model identifier is correct for the chosen provider.
-- Missing features (webSearch/think/image): switch to a model that supports the capability and update your CCR mapping (via UI or JSON config).
diff --git a/docs/supported-coding-agents/claude-code.mdx b/docs/supported-coding-agents/claude-code.mdx
deleted file mode 100644
index 4f90fd3d..00000000
--- a/docs/supported-coding-agents/claude-code.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-# Claude Code
-
-## Installation
-
-Claude Code is now available via npx - no separate installation required!
-
-## Authentication
-
-You need to authenticate with Claude Code outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Claude Code GitHub page](https://github.com/anthropics/claude-code).
diff --git a/docs/supported-coding-agents/codex.mdx b/docs/supported-coding-agents/codex.mdx
deleted file mode 100644
index 35d61b1f..00000000
--- a/docs/supported-coding-agents/codex.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-# Codex
-
-## Installation
-
-OpenAI Codex is now available via `npx` - no separate installation required!
-
-## Authentication
-
-You need to configure your OpenAI API credentials before using Codex. Please set the `OPENAI_API_KEY` environment variable. For more details, see the [OpenAI documentation](https://platform.openai.com/docs/guides/code).
diff --git a/docs/supported-coding-agents/cursor-cli.mdx b/docs/supported-coding-agents/cursor-cli.mdx
deleted file mode 100644
index 04300992..00000000
--- a/docs/supported-coding-agents/cursor-cli.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-# Cursor CLI
-
-## Installation
-
-Install Cursor CLI using the official guide: https://docs.cursor.com/en/cli/installation. On most systems you can run `curl https://cursor.com/install -fsS | bash`, then verify with `cursor-agent --version`.
-
-## Authentication
-
-Sign in with `cursor-agent login` (opens a browser). You can also set the `CURSOR_API_KEY=...` environment variable. Full instructions: https://docs.cursor.com/en/cli/reference/authentication
diff --git a/docs/supported-coding-agents/gemini-cli.mdx b/docs/supported-coding-agents/gemini-cli.mdx
deleted file mode 100644
index e1978eac..00000000
--- a/docs/supported-coding-agents/gemini-cli.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-# Gemini CLI
-
-## Installation
-
-Gemini CLI is now available via npx - no separate installation required!
-
-## Authentication
-
-You need to authenticate with Gemini CLI outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Gemini CLI GitHub page](https://github.com/google-gemini/gemini-cli).
diff --git a/docs/supported-coding-agents/qwen-code.mdx b/docs/supported-coding-agents/qwen-code.mdx
deleted file mode 100644
index 37a5d807..00000000
--- a/docs/supported-coding-agents/qwen-code.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-# Qwen Code
-
-## Installation
-
-Qwen Code is available via npx - no separate installation required!
-
-## Authentication
-
-You need to authenticate with Qwen outside of Vibe Kanban before using it. Please follow the authentication instructions in the official Qwen documentation: https://github.com/QwenLM/qwen-code
diff --git a/docs/supported-coding-agents/sst-opencode.mdx b/docs/supported-coding-agents/sst-opencode.mdx
deleted file mode 100644
index 5caba718..00000000
--- a/docs/supported-coding-agents/sst-opencode.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-# SST OpenCode
-
-## Installation
-
-SST OpenCode is now available via `npx` - no separate installation required!
-
-## Authentication
-
-You need to authenticate with SST OpenCode outside of Vibe Kanban before using it. Please follow the authentication instructions on the [SST OpenCode GitHub page](https://github.com/sst/opencode).
diff --git a/docs/user-guide/agent-configurations.mdx b/docs/user-guide/agent-configurations.mdx
deleted file mode 100644
index ac8b674f..00000000
--- a/docs/user-guide/agent-configurations.mdx
+++ /dev/null
@@ -1,102 +0,0 @@
-# Agent Profiles & Variants
-
-Agent profiles let you define multiple named variants for each supported coding agent. Variants capture small configuration differences (e.g., planning vs. coding, model choice, sandbox/approval levels) you can quickly select when creating an attempt or sending a follow‑up.
-
-Profiles are used anywhere an agent runs:
-
-- Onboarding: pick your default agent and optional variant
-- Settings → General: set the default agent configuration
-- Create Attempt dialog: choose agent and variant per attempt
-- Follow‑ups: continue using the attempt's selected profile/variant
-
-## Where To Configure
-
-Open Settings → Agents. You can edit agent configurations in two ways:
-
-- Form editor: guided fields per agent
-
-
-
-- JSON editor: edit the underlying `profiles.json` directly
-
-
-
-The page shows the exact file path where your config is stored (profiles.json). The app saves only your overrides; built‑in defaults remain available and cannot be deleted.
-
-## JSON Structure
-
-The configuration file is a JSON object with an `executors` map. Each executor (agent) contains one or more variants. Every variant holds a single object for that agent with its options.
-
-Example (abridged):
-
-```json
-{
- "executors": {
- "CLAUDE_CODE": {
- "DEFAULT": { "CLAUDE_CODE": { "dangerously_skip_permissions": true } },
- "PLAN": { "CLAUDE_CODE": { "plan": true } },
- "ROUTER": { "CLAUDE_CODE": { "claude_code_router": true, "dangerously_skip_permissions": true } }
- },
- "GEMINI": {
- "DEFAULT": { "GEMINI": { "model": "default", "yolo": true } },
- "FLASH": { "GEMINI": { "model": "flash", "yolo": true } }
- },
- "CODEX": {
- "DEFAULT": { "CODEX": { "sandbox": "danger-full-access" } },
- "HIGH": { "CODEX": { "sandbox": "danger-full-access", "model_reasoning_effort": "high" } }
- }
- }
-}
-```
-
-Notes:
-
-- Variant names are case‑insensitive and normalized to SCREAMING_SNAKE_CASE.
-- `DEFAULT` is reserved and always present; you can add more variants (e.g., `PLAN`, `FLASH`).
-- You can't remove built‑in executors or their built‑in variants, but you can override their values or add new variants.
-
-## Per‑Agent Options (quick reference)
-
-- CLAUDE_CODE
- - `plan: boolean` – enable planning mode
- - `claude_code_router: boolean` – route across multiple Claude Code instances
- - `dangerously_skip_permissions: boolean` – skip permission prompts (unsafe)
- - Docs: https://docs.anthropic.com/en/docs/claude-code/cli-reference#cli-flags
-- GEMINI
- - `model: "default" | "flash"`
- - `yolo: boolean` – run without confirmations
- - Docs: https://google-gemini.github.io/gemini-cli/
-- AMP
- - `dangerously_allow_all: boolean` – allow all actions (unsafe)
- - Docs: https://ampcode.com/manual#cli
-- CODEX
- - `sandbox: "read-only" | "workspace-write" | "danger-full-access"`
- - `approval: "untrusted" | "on-failure" | "on-request" | "never"`
- - `oss: boolean`, `model: string`, `model_reasoning_effort: "low" | "medium" | "high"`, `model_reasoning_summary: "auto" | "concise" | "detailed" | "none"`
- - Docs: https://github.com/openai/codex
-- CURSOR
- - `force: boolean`, `model: string`
- - Docs: https://docs.cursor.com/en/cli/reference/parameters
-- OPENCODE
- - `model: string`, `agent: string`
- - Docs: https://opencode.ai/docs/cli/#flags-1
-- QWEN_CODE
- - `yolo: boolean`
- - Docs: https://qwenlm.github.io/qwen-code-docs/en/cli/index
-
-Common options supported by several agents:
-
-- `append_prompt: string | null` – text appended to the system/prompt
-- `base_command_override: string | null` – override the underlying CLI command
-- `additional_params: string[] | null` – extra CLI args
-
-Use these carefully; "dangerously_…" flags bypass confirmations and can perform destructive actions.
-
-## Selecting Defaults vs. Per‑Attempt
-
-- Default: Set under Settings → General → "Default Agent Configuration."
-- Per Attempt: Use the create attempt dialog to pick a different agent/variant for that run.
-
-## MCP Servers
-
-MCP (Model Context Protocol) servers are configured per agent under Settings → MCP Servers. This is separate from profiles but complements them. See the [MCP Support](/docs/user-guide/vibe-kanban-mcp-server) guide.
diff --git a/docs/user-guide/creating-projects.mdx b/docs/user-guide/creating-projects.mdx
deleted file mode 100644
index 6b186c10..00000000
--- a/docs/user-guide/creating-projects.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
-# Creating Projects
-
-Before you can create tasks and execute coding agents, you must create a project.
-
-
-
-Each project represents a git repo and can be configured with its own setup and dev server scripts.
-
-## Git
-
-You can either specify an existing Git repo, or Vibe Kanban will create a blank one for you if you choose the "Create new project" option.
-
-## Setup Scripts
-
-Setup scripts will be run before the coding agent is executed. This is useful for installing dependencies, for example you might run `npm install` or `cargo build`. This will save you time as your agent won't need to figure out that these commands haven't already been run.
-
-_Note, each time a coding agent is executed it runs in a [git worktree](https://git-scm.com/docs/git-worktree) which is unlikely to contain your dependencies, configs, .env etc..._
-
-## Dev Server Scripts
-
-The dev server script is run whenever you press the "run dev server" button. It's useful for quickly reviewing work after a coding agent has run.
-
-At the moment only one dev server can be running for each project, so if you start one it will kill any that are already running.
-
-## Cleanup Scripts
-
-Cleanup scripts run after a coding agent finishes. You can use these to tidy up the workspace, remove temporary files, or perform any post-execution cleanup. For example, you might run:
-
-```bash
-npm run clean
-```
diff --git a/docs/user-guide/creating-task-attempts.mdx b/docs/user-guide/creating-task-attempts.mdx
deleted file mode 100644
index 98b561d8..00000000
--- a/docs/user-guide/creating-task-attempts.mdx
+++ /dev/null
@@ -1,40 +0,0 @@
-# Task Attempts
-
-Task attempts represent one run of a coding agent against a task. Any follow up questions in the same coding agent session will be attached to the same task attempt.
-
-## Running Setup Scripts
-
-
-
-When you start a task attempt, if specified in the project settings, the setup script is run automatically.
-
-## Running Coding Agents
-
-
-
-After any setup scripts have run, the coding agent is executed with your task title and description in the prompt. The agent's logs are streamed back to the UI in real time.
-
-### Profiles & Variants
-
-Before starting, select an agent profile (agent) and, if available, a variant. Profiles and variants let you quickly switch between different configurations for the same agent (for example a planning-focused variant). You can manage these under Settings → Agents. See [Agent Profiles & Variants](/docs/user-guide/agent-configurations) for details.
-
-## Follow Up questions
-
-When the execution has finished, you can ask a follow up question using the box at the bottom of the task attempt dialog.
-
-## Task Attempt Toolbar
-
-
-
-You can use the task attempt toolbar to perform useful actions:
-
-- `Dev Server` - Start a dev server (this will kill any existing dev servers running in this project)
-- `History` - View any previous attempts at this task
-- `Rebase` - If enabled, communicates that the task branch is behind its base branch, if clicked will attempt to rebase (will fail on conflict)
-- `Create PR` - Opens a dialog to create a PR in GitHub
-- `Merge` - Merges the branch into its base branch
-- `New Attempt` - Opens the create attempt dialog so you can start over
-
-## Worktrees
-
-Under the hood, Vibe Kanban relies on Git worktrees to create isolated environments for each task attempt. These should be considered ephemeral and are automatically cleaned up after each run.
diff --git a/docs/user-guide/creating-task-templates.mdx b/docs/user-guide/creating-task-templates.mdx
deleted file mode 100644
index bb0dda4c..00000000
--- a/docs/user-guide/creating-task-templates.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
-# Task Templates
-
-Task templates let you define reusable task formats that speed up task creation. Templates can be created globally (across all projects) or scoped to individual projects.
-
-## Global Task Templates
-
-Global templates are managed in **Global Settings → Task Templates**. This view lets you define templates available in every project.
-
-
-
-Use the **Add Template** button to create a new global template, and the edit (✏️) or delete (🗑️) icons to modify existing templates.
-
-## Project Task Templates
-
-Project templates are scoped to a single project. To manage them, open your project and click the library icon in the project's page to access the Template Library, then select **Manage Templates**.
-
-
-
-Within this window, use **Add Template**, **Edit** (✏️), and **Remove** (🗑️) controls to manage project‑specific templates.
-
-## Using Templates
-
-When creating a task, use the **Use a template** dropdown to pick from your global or project templates. Selecting a template will prefill the task title and description.
diff --git a/docs/user-guide/creating-tasks.mdx b/docs/user-guide/creating-tasks.mdx
deleted file mode 100644
index 26a78d98..00000000
--- a/docs/user-guide/creating-tasks.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
-# Creating Tasks
-
-
-
-Once you've created a project, you can add tasks by clicking the `Add Task` button in the navigation section of the project kanban page. Creating a task adds it to the project's kanban board, but doesn't automatically start trying to work on the task with a coding agent.
-
-## Using Templates
-
-
-
-When adding a new task, you can choose from your global or project templates via the **Use a template** dropdown. Selecting a template will prefill the task title and description based on your chosen template. See [Task Templates](/docs/user-guide/creating-task-templates) for details.
-
-## Task Attempts
-
-
-
-To start a coding agent working on a task you'll need to create a task attempt. You can specify the base branch, the agent to use, and (if available) a variant. By default your currently checked out branch and your default agent configuration (from Settings) are selected.
-
-- Select Profile: pick the agent (e.g., CLAUDE_CODE, GEMINI, CODEX)
-- Select Variant: if the chosen agent has variants, pick one (e.g., DEFAULT, PLAN)
-
-_Tip: "Create & Start" adds the task to the board and immediately creates a task attempt using your default agent configuration._
-
-You can learn more about task attempts on the [Task Attempts](./creating-task-attempts) page.
-
-## Columns
-
-Tasks are added to the "To do" column, and can be freely dragged into any column. Dragging a task into a particular column won't trigger any functionality, but the task may move into a different column based on actions that are taken like starting coding agents. These are documented below:
-
-- Task attempt created: task moves to `In Progress`
-- Task attempt finished (success or failure): task moves to `In Review`
-- Task attempt merged: task moves to `Done`
-- Task attempt PR merged on GitHub: task moves to `Done` (polls GitHub every 60s)
diff --git a/docs/user-guide/vibe-kanban-mcp-server.mdx b/docs/user-guide/vibe-kanban-mcp-server.mdx
deleted file mode 100644
index 9a22b753..00000000
--- a/docs/user-guide/vibe-kanban-mcp-server.mdx
+++ /dev/null
@@ -1,53 +0,0 @@
-# MCP Support
-
-Vibe Kanban ships with an MCP (Model Context Protocol) server, allowing you to manage projects and tasks from any coding agent, including coding agents started by vibe-kanban itself.
-
-## Setting Up MCP Integration
-
-### Option 1: Using the Web Interface
-
-This works if you're adding the Vibe Kanban MCP server to any [supported coding agent](/docs/supported-coding-agents).
-
-1. Navigate to the "MCP Servers" page in Vibe Kanban
-2. Click the `Add Vibe-Kanban MCP` button
-3. Click the `Save Settings` button
-
-
-
-### Option 2: Manual Configuration
-
-You can manually add the MCP server to your coding agent's configuration. Add the following configuration to your agent's MCP servers configuration:
-
-```json
-{
- "mcpServers": {
- "vibe_kanban": {
- "command": "npx",
- "args": ["-y", "vibe-kanban", "--mcp"]
- }
- }
-}
-```
-
-## Using MCP with Coding Agents
-
-Once you have the MCP server configured, you can leverage it to streamline your project planning workflow:
-
-1. **Plan Your Work**: Describe a large feature or project to your coding agent
-2. **Request Task Creation**: At the end of your task description, simply add "then turn this plan into tasks"
-3. **Automatic Task Generation**: Your coding agent will use the Vibe Kanban MCP server to automatically create structured tasks in your project
-
-## Example Usage
-
-```
-I need to build a user authentication system with the following features:
-- User registration with email validation
-- Login/logout functionality
-- Password reset capability
-- Session management
-- Protected routes
-
-Then turn this plan into tasks.
-```
-
-The coding agent will break this down into individual tasks and add them to your Vibe Kanban project automatically.
+
+
+
+
+
+
+
+
+
+
+
+
+## Themes
+
+Switch between light and dark themes to suit your preference.
+
+## Default Agent Configuration
+
+Choose the default agent and variant for new task attempts. This profile is pre-selected when creating new task attempts and follow-ups.
+
+1. **Select an agent** (e.g., Claude Code, Gemini CLI, Codex)
+2. **Choose a variant** if available (e.g., Default, Plan, Router)
+
+
+
+
+## Creating Your Project
+Click the **Create Project** button to choose from two options:
+- **From existing git repository**: Browse your file system and select from a list of git repositories sorted by recent activity
+- **Create blank project**: Generate a new git repository from scratch
+Each project represents a git repository. After creation, you can configure it with setup scripts, dev server scripts, and other settings.
+
+
+
+
+
+After creating a project, add tasks by clicking the **plus (+) icon** in the top right of your project kanban page, or by using the keyboard shortcut **`c`**. Creating a task adds it to your kanban board without automatically starting a coding agent.
+
+## Using Templates
+
+
+
+
+
+When adding a task, you can select from your saved templates:
+
+1. Click the **Use a template** dropdown
+2. Choose from available global or project templates
+3. The template automatically populates the task title and description
+
+
+
+
+To activate a coding agent on your task, create a task attempt:
+
+
+
+
+
+
+To create a subtask from an existing task attempt:
+
+
+
+
+When viewing a parent task, you can see its subtasks in the **Task Relationships** panel. This collapsible section shows:
+
+- **Child Tasks** with a count (e.g., "CHILD TASKS (1)")
+- Individual subtask titles with links to view them
+- Easy navigation between parent and child tasks
+
+This helps you track progress across all related work items and understand the task hierarchy at a glance.
+
+## Viewing Subtask Details
+
+
+
+
+
+When viewing a subtask, the **Task Relationships** panel displays:
+
+- **Parent Task** section showing the parent task title
+- Direct link to navigate to the parent task
+- Clear visual indication that this is a child task
+- Context about the parent-child relationship
+
+The subtask also shows its own **Create Subtask** button, allowing you to create nested subtasks if needed.
+
+## How Subtasks Work
+
+Subtasks in Vibe Kanban follow these key principles:
+
+### Git Branching Workflow
+
+Subtasks create their own feature branches that can work independently while maintaining connection to the parent task:
+
+```mermaid
+gitGraph
+ commit id: "main"
+ branch feature/parent-task
+ checkout feature/parent-task
+ commit id: "Parent Task Start"
+ commit id: "Initial work"
+
+ branch feature/subtask-1
+ checkout feature/subtask-1
+ commit id: "Subtask 1: Backend API"
+ commit id: "API implementation"
+ commit id: "API tests"
+
+ checkout feature/parent-task
+ branch feature/subtask-2
+ checkout feature/subtask-2
+ commit id: "Subtask 2: Frontend UI"
+ commit id: "Component creation"
+ commit id: "UI styling"
+
+ checkout feature/parent-task
+ branch feature/subtask-3
+ checkout feature/subtask-3
+ commit id: "Subtask 3: Integration"
+ commit id: "Connect API to UI"
+
+ checkout feature/parent-task
+ merge feature/subtask-1
+ merge feature/subtask-2
+ merge feature/subtask-3
+ commit id: "Parent Task Complete"
+
+ checkout main
+ merge feature/parent-task
+```
+
+### Parent-Child Relationships
+
+- Subtasks are linked to specific **task attempts**, not just tasks
+- Each subtask knows which attempt created it
+- Multiple subtasks can be created from the same parent attempt
+
+### Branch Inheritance
+
+- Subtasks automatically inherit the base branch from their parent attempt
+- This ensures subtasks work within the same development context
+- You can modify the branch when creating the subtask if needed
+
+### Independent Task Lifecycle
+
+- Subtasks appear as regular tasks on your kanban board
+- Each subtask has its own lifecycle (To do → In Progress → In Review → Done)
+- Subtasks can have their own task attempts and coding agents
diff --git a/docs/core-features/task-details-full-screen.mdx b/docs/core-features/task-details-full-screen.mdx
new file mode 100644
index 00000000..582e9a8b
--- /dev/null
+++ b/docs/core-features/task-details-full-screen.mdx
@@ -0,0 +1,135 @@
+---
+title: "Task Details Full Screen Mode"
+sidebarTitle: "Full Screen Mode"
+description: "Complete guide to using the task details full screen mode for development workflows, including dev server, git operations, logs, diffs, and process monitoring"
+---
+
+## Accessing Full Screen Mode
+
+Click the **Maximise** button (⛶) in the task details header to expand the view to occupy the full right side of your screen. Some task actions (like "View full diff") automatically switch to full screen mode for better visibility.
+
+
+
+
+
+## Interface Layout
+
+Full screen mode uses a two-column layout:
+
+### Left Sidebar
+- **Task Information**: Title, description, and metadata
+- **Development Toolbar**: Primary development actions
+- **TODOs**: Task checklist and progress tracking
+- **Relationships**: Subtasks and parent task links
+
+### Right Panel
+- **Tab Navigation**: Switch between Logs, Diffs, and Processes
+- **Content Area**: Active tab content with real-time updates
+- **Follow-up Section**: Additional context and actions
+
+## Core Features
+
+### Development Server
+
+Start and manage your project's development environment directly from the task interface.
+
+**Controls:**
+- **Dev** (▶️): Start the development server using your project's configured dev script
+- **Stop Dev** (⏹️): Terminate the running development server
+- **View Logs** (📄): Jump to process logs to monitor server output
+
+The development server runs in a git worktree environment and streams all output to the Processes tab. Click the logs button next to the dev server control to jump directly to the process logs for real-time monitoring.
+
+### Git Operations
+
+#### Rebase
+Keep your task branch up-to-date with the latest changes from the base branch.
+
+- **Automatic Detection**: The rebase button appears when your branch is behind the base branch
+- **Conflict Handling**: Any merge conflicts are displayed in the Diffs tab
+
+#### Merge
+Integrate your completed work back into the base branch.
+
+- **Availability**: Disabled when an open pull request exists
+- **Success Indication**: A "Merged!" notification confirms successful integration
+
+#### Push & Pull Request Management
+- **Create PR**: Opens pull request creation dialog for new branches
+- **Push to PR**: Updates existing pull request with latest changes
+- **Auto-detection**: Automatically detects existing PRs and adjusts button behavior
+
+### Task Management
+
+#### History & Attempts
+View and manage all task attempts from the full screen interface.
+
+- **History**: View all previous attempts for this task, review execution status and outcomes, and switch between different attempts to compare results
+- **New Attempt**: Create additional attempts when previous approaches didn't work as expected or when testing different implementation strategies
+
+
+
+
+#### Diffs Tab
+The Diffs tab provides a visual representation of all code changes made during task execution. It shows a git diff between your branch and the base branch, with syntax highlighting and language-aware code formatting. You can see a summary of added, modified, and deleted files with precise line-by-line change tracking and context.
+
+
+
+
+
+Learn more in [Reviewing Code Changes](/core-features/reviewing-code-changes).
+
+#### Processes Tab
+The Processes tab displays a timeline view of all running and completed processes. You can track the status of running, completed, failed, and stopped processes with their complete execution timeline. Click any process to view its specific output logs, and use the interactive controls to stop running processes directly from the interface.
+
+
+
+
+
+## Navigation & Controls
+
+### Keyboard Shortcuts
+- **Escape**: Exit full screen mode and return to sidebar view
+- **Tab Navigation**: Use browser tab controls to switch between Logs, Diffs, and Processes
+
+
+
+## Exiting Full Screen Mode
+
+- Click the **Minimize** button in the header
+- Press **Escape** key
+- Click the **×** button to close the task panel entirely
+- Navigate to a different task or project
+
+The interface gracefully transitions back to the compact sidebar view while preserving your work context.
+
+## Related Documentation
+
+- [Creating Task Attempts](/core-features/creating-task-attempts) - Learn about task attempt lifecycle
+- [Reviewing Code Changes](/core-features/reviewing-code-changes) - Deep dive into diff analysis
+- [Creating Tasks](/core-features/creating-tasks) - Task creation and management
+- [Agent Configurations](/configuration-customisation/agent-configurations) - Customise AI agent behaviour
diff --git a/docs/development.mdx b/docs/development.mdx
deleted file mode 100644
index ac633bad..00000000
--- a/docs/development.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: 'Development'
-description: 'Preview changes locally to update your docs'
----
-
-
-
-
-## Code formatting
-
-We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
-
-## Troubleshooting
-
-
-
-## Image
-
-### Using Markdown
-
-The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
-
-```md
-
-```
-
-Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
-
-### Using embeds
-
-To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
-
-```html
-
-```
-
-## Embeds and HTML elements
-
-
-
-
+
+
+When you're ready to create a PR, get a streamlined dialog that:
+- Pre-fills title and description from your task details
+- Lets you select the target branch (defaults to main/master)
+- Validates that your branch is ready to go
+- Provides direct links to your new pull request
+
+### Smart Push/PR Button
+
+
+
+
+
+Each task attempt gets a smart button that adapts to your current state:
+- **"Create PR"** when ready to share your work
+- **"Push X commits"** when you have changes to upload
+- **"Push to PR"** when updating an existing pull request
+- **"Pushed!"** confirmation after successful operations
+
+
+
+
+Click **Connect GitHub Account** in General Settings to authenticate with GitHub using device flow authentication.
+
+
+
+
+
+The authentication process is simple:
+1. Click **Sign in with GitHub**
+2. Visit the provided GitHub URL in your browser
+3. Enter the device code shown in the dialog
+4. Authorize Vibe Kanban in your browser
+5. Return to complete the setup
+
+**Required Permissions**: Vibe Kanban needs access to your repositories (`repo`), basic profile info (`read:user`), and email address (`user:email`) for Git commits.
+
+
+
+
+## Popular MCP Servers
+
+Vibe Kanban provides one-click installation for popular MCP servers.
+
+
+
+
+
+## Adding Custom MCP Servers
+
+You can also add your own MCP servers by configuring them manually:
+
+
+
+
+Configure the Vibe Kanban MCP server in Raycast by adding the server details.
+
+
+
+Once configured, you'll see the Vibe Kanban MCP server listed and ready to use in Raycast.
+
+
+
+### Example: CCR model mapping (default/background/think/etc.)
+
+
+
+
+
+## Configure Vibe Kanban
+
+Vibe Kanban does not ship a default configuration for CCR. Add configurations to the existing Claude Code agent:
+
+1) Open the "Coding Agent Configurations" page.
+2) Add a new configuration for the Claude Code agent (or edit an existing one).
+3) Enable the `claude_code_router` checkbox.
+4) Optionally set a model string to target a specific CCR provider/model.
+
+See the [Agent Profiles & Variants](/configuration-customisation/agent-configurations) guide for managing agent configurations.
+
+Model string format: `
+
+
+## Using CCR in Vibe Kanban
+
+When creating a Task Attempt, select the coding agent and configuration: choose the Claude Code agent, then pick one of your CCR-enabled configurations.
+
+## Troubleshooting
+
+- Authentication errors: verify your API keys/provider settings in CCR (via UI or JSON config).
+- Model not found: confirm the model identifier is correct for the chosen provider.
+- Missing features (webSearch/think/image): switch to a model that supports the capability and update your CCR mapping (via UI or JSON config).
+