### Configure Node.js Worktree Setup with Commands

Source: https://docs.firebender.com/multi-agent/worktrees

Sets up a Node.js worktree by installing dependencies and copying environment variables. This example uses an array of shell commands executed sequentially.

```json
{
  "worktrees": {
    "setup-worktree": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env"
    ]
  }
}
```

--------------------------------

### Provide example usage in documentation

Source: https://docs.firebender.com/multi-agent/skills

Shows how to include concrete command-line examples within skill documentation to guide users on proper tool usage.

```bash
# Search for issues
gh search issues "bug" --repo=owner/repo

# Clone for analysis
cd /tmp && git clone https://github.com/owner/repo.git
```

--------------------------------

### Configure Python Worktree Setup with Virtual Environment

Source: https://docs.firebender.com/multi-agent/worktrees

Sets up a Python worktree by creating a virtual environment, installing dependencies, and copying environment variables. This example uses an array of shell commands.

```json
{
  "worktrees": {
    "setup-worktree": [
      "python -m venv venv",
      "source venv/bin/activate && pip install -r requirements.txt",
      "cp $ROOT_WORKTREE_PATH/.env .env"
    ]
  }
}
```

--------------------------------

### Configure OS-Specific Worktree Setup Commands

Source: https://docs.firebender.com/multi-agent/worktrees

Provides different setup commands for Unix/macOS and Windows worktrees. This allows for OS-tailored dependency installation and file copying.

```json
{
  "worktrees": {
    "setup-worktree-unix": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env",
      "chmod +x scripts/*.sh"
    ],
    "setup-worktree-windows": [
      "npm ci",
      "copy %ROOT_WORKTREE_PATH%\.env"
    ]
  }
}
```

--------------------------------

### Configure Worktree Setup for Building and Linking Dependencies

Source: https://docs.firebender.com/multi-agent/worktrees

Sets up a worktree by installing and building project dependencies, then copying a specific environment file. This configuration uses pnpm package manager.

```json
{
  "worktrees": {
    "setup-worktree": [
      "pnpm install",
      "pnpm run build",
      "cp $ROOT_WORKTREE_PATH/.env.local .env.local"
    ]
  }
}
```

--------------------------------

### Configure Worktree Setup with Database Migrations

Source: https://docs.firebender.com/multi-agent/worktrees

Sets up a worktree for a project that includes database migrations. It installs dependencies, copies environment variables, and runs migration commands.

```json
{
  "worktrees": {
    "setup-worktree": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env",
      "npm run db:migrate"
    ]
  }
}
```

--------------------------------

### Unix Script for Worktree Setup

Source: https://docs.firebender.com/multi-agent/worktrees

A bash script to set up a worktree on Unix-like systems. It installs Node.js dependencies, copies an environment file, and runs database migrations.

```bash
#!/bin/bash
set -e
# Install dependencies
npm ci
# Copy environment file
cp "$ROOT_WORKTREE_PATH/.env" .env
# Run database migrations
npm run db:migrate
echo "Worktree setup complete!"

```

--------------------------------

### Configure Worktree Setup Using Script Files

Source: https://docs.firebender.com/multi-agent/worktrees

Configures worktree setup by referencing OS-specific script files for Unix/macOS and Windows, with a generic fallback. This is useful for complex setup procedures.

```json
{
  "worktrees": {
    "setup-worktree-unix": "setup-worktree-unix.sh",
    "setup-worktree-windows": "setup-worktree-windows.ps1",
    "setup-worktree": [
      "echo 'Using generic fallback. For better support, define OS-specific scripts.'"
    ]
  }
}
```

--------------------------------

### Windows PowerShell Script for Worktree Setup

Source: https://docs.firebender.com/multi-agent/worktrees

A PowerShell script to set up a worktree on Windows. It installs Node.js dependencies, copies an environment file, and runs database migrations.

```powershell
$ErrorActionPreference = 'Stop'
# Install dependencies
npm ci
# Copy environment file
Copy-Item "$env:ROOT_WORKTREE_PATH\.env" .env
# Run database migrations
npm run db:migrate
Write-Host "Worktree setup complete!"

```

--------------------------------

### Debug Worktree Setup by Logging Output

Source: https://docs.firebender.com/multi-agent/worktrees

Configures the worktree setup to redirect all command output to a log file for debugging purposes. This helps in diagnosing issues during the setup process.

```json
{
  "worktrees": {
    "setup-worktree": [
      "npm ci 2>&1 | tee /tmp/worktree-setup.log",
      "cp $ROOT_WORKTREE_PATH/.env .env 2>&1 | tee -a /tmp/worktree-setup.log"
    ]
  }
}
```

--------------------------------

### Kotlin: Example of Database Schema

Source: https://docs.firebender.com/api-reference/skills

Provides a concrete example of Kotlin code, specifically a Room database schema definition. This snippet illustrates how to include practical, runnable code examples within skill documentation to demonstrate usage and functionality.

```kotlin
// Create Room database
@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}
```

--------------------------------

### YAML: Specific Skill Description Example

Source: https://docs.firebender.com/api-reference/skills

Provides an example of a well-written, specific skill description in YAML format. A good description includes the skill's purpose, the technologies it uses, and the scenarios in which it should be invoked. This improves the accuracy of auto-triggering and manual discovery.

```yaml
description: Writes comprehensive unit and UI tests for Android apps using JUnit 5, MockK, and Compose Testing. Use when creating tests, improving test coverage, or debugging test failures.
```

--------------------------------

### Example: Code Review Command Configuration

Source: https://docs.firebender.com/api-reference/commands

This markdown snippet shows a complete example of a 'review diff' command configuration. It includes YAML frontmatter specifying the name, description, and mode, followed by the prompt instructions for reviewing staged changes.

```markdown
---
name: review diff
description: Review staged changes before commit
mode: read
---

Review the current git diff for:

1. **Bugs**: Logic errors, null pointer issues, race conditions
2. **Security**: Input validation, SQL injection, XSS vulnerabilities
3. **Performance**: N+1 queries, unnecessary allocations, blocking calls
4. **Style**: Naming conventions, code organization, documentation

Provide actionable feedback with specific line references.
```

--------------------------------

### YAML: General Skill Description Example

Source: https://docs.firebender.com/api-reference/skills

Illustrates a less effective, general skill description in YAML format. This type of description is too broad and may not accurately trigger the skill or inform the user of its specific capabilities. It's recommended to be more detailed, as shown in the 'Specific Skill Description Example'.

```yaml
description: Helps with testing
```

--------------------------------

### Configure Worktree Setup with Command Arrays (JSON)

Source: https://docs.firebender.com/api-reference/syntax

Demonstrates how to define worktree setup commands using arrays of strings directly within the firebender.json configuration. These commands are executed sequentially in the worktree. Supports general, Unix, and Windows specific commands.

```json
{
  "worktrees": {
    "setup-worktree": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env"
    ]
  }
}
```

```json
{
  "worktrees": {
    "setup-worktree-unix": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env",
      "chmod +x scripts/*.sh"
    ],
    "setup-worktree-windows": [
      "npm ci",
      "copy %ROOT_WORKTREE_PATH%\.env .env"
    ]
  }
}
```

--------------------------------

### Example: Changelog Generator Command Configuration

Source: https://docs.firebender.com/api-reference/commands

This markdown snippet provides an example configuration for a 'write changelog' command. It uses YAML frontmatter to set the name, description, and model, and includes prompt instructions for generating a changelog entry from recent git commits.

```markdown
---
name: write changelog
description: Generate changelog entry from recent commits
model: default
mode: write
---

Analyze recent commits and generate a changelog entry.

1. Run `git log --oneline -20` to see recent commits
2. Group changes by type (features, fixes, improvements)
3. Write user-friendly descriptions
4. Update CHANGELOG.md with the new entry
```

--------------------------------

### Install PDF processing dependencies

Source: https://docs.firebender.com/multi-agent/skills

Installs the necessary Python packages for PDF manipulation via pip.

```bash
pip install pypdf pdfplumber
```

--------------------------------

### Define Rule Files with YAML Frontmatter

Source: https://docs.firebender.com/api-reference/rules

Examples of creating .mdc rule files using YAML frontmatter to define descriptions, file matching globs, and application scope. These files guide the AI in maintaining project-specific coding standards.

```markdown
---
description: Kotlin coding standards for this project
globs: "*.kt, *.kts"
alwaysApply: false
---

# Kotlin Style Guidelines

- Use Kotlin coroutines for async operations, never `runBlocking`
- Prefer data classes for simple data holders
- Use `@SerializedName` for Retrofit/Gson classes (code gets obfuscated)
- Follow Material Design 3 guidelines for UI components
```

```markdown
This is a food delivery app similar to DoorDash.

Key technologies:
- Kotlin with Jetpack Compose for Android
- Room for local database
- Retrofit for networking
- Kotlin coroutines for async operations
```

--------------------------------

### Android Room Database Query Example (Kotlin)

Source: https://docs.firebender.com/api-reference/skills

Provides an example of a suspend function for querying the Android Room database. This snippet demonstrates how to define a query with a parameter and an order clause. It is intended for use within an Android application utilizing the Room persistence library.

```kotlin
import androidx.room.Query

// Assuming User is a data class representing the table structure

@Query("SELECT * FROM users WHERE age > :minAge ORDER BY name ASC")
suspend fun getUsersOlderThan(minAge: Int): List<User>

```

--------------------------------

### Custom Agent Prompt Example

Source: https://docs.firebender.com/get-started/quickstart

An example of a prompt used to create a custom coding agent within Firebender. This prompt specifies the agent's persona (Jake Wharton), its capabilities (code review, catching bad practices), and its interaction style (concise, clear feedback).

```text
Build an AI Jake Wharton to review my code:
- He is very good at catching bad practice
- See his comments on retrofit using gh cli to get an idea of his style
- Same level of concise and clear PR feedback to whip me into shape
- Make sure to also get his pfp as a file
- Tools for ability to read, no write access, or execute access.
```

--------------------------------

### Configure Worktree Setup with Script Files (JSON)

Source: https://docs.firebender.com/api-reference/syntax

Illustrates how to specify script file paths for worktree setup in firebender.json. The configuration can point to a single script for all OS, or separate scripts for Unix and Windows systems. These scripts are executed relative to the firebender.json file.

```json
{
  "worktrees": {
    "setup-worktree": "setup-worktree.sh"
  }
}
```

```json
{
  "worktrees": {
    "setup-worktree-unix": "setup-worktree-unix.sh",
    "setup-worktree-windows": "setup-worktree-windows.ps1"
  }
}
```

--------------------------------

### List GitHub Repositories

Source: https://docs.firebender.com/api-reference/list-github-repositories

Retrieve a list of GitHub repositories accessible to the authenticated user via the connected GitHub App installation.

```APIDOC
## GET /v0/repositories

### Description
Retrieve a list of GitHub repositories accessible to the authenticated user via the connected GitHub App installation.

### Method
GET

### Endpoint
/v0/repositories

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **repositories** (array) - Array of GitHub repositories the user has access to
  - **owner** (string) - The owner of the repository (user or organization)
  - **name** (string) - The name of the repository
  - **repository** (string) - The full URL to the GitHub repository

#### Response Example
```json
{
  "repositories": [
    {
      "owner": "your-org",
      "name": "your-repo",
      "repository": "https://github.com/your-org/your-repo"
    }
  ]
}
```

#### Error Responses
- **401** - Unauthorized - invalid or missing API key
- **429** - Rate limit exceeded
- **500** - Internal server error
```

--------------------------------

### Firebender Matcher Configuration Example

Source: https://docs.firebender.com/multi-agent/hooks

This JSON snippet demonstrates how to configure matchers for different hook types in Firebender. It shows how to specify commands and associate them with specific matcher patterns for filtering hook execution.

```json
{
  "hooks": {
    "preToolUse": [
      {
        "command": "./validate-shell.sh",
        "matcher": "Shell"
      }
    ],
    "beforeShellExecution": [
      {
        "command": "./approve-network.sh",
        "matcher": "curl|wget|nc "
      }
    ]
  }
}
```

--------------------------------

### GET /v0/agents/{id}/vnc

Source: https://docs.firebender.com/api-reference/get-vnc-access

Retrieves a signed VNC URL to monitor an agent's activity in real-time. The session is valid for 24 hours.

```APIDOC
## GET /v0/agents/{id}/vnc

### Description
Get a signed VNC URL to watch the agent working live. The URL is valid for 24 hours. Only available for agents in CREATING, SETUP, or RUNNING state.

### Method
GET

### Endpoint
/v0/agents/{id}/vnc

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier for the cloud agent (e.g., fb_abc123xyz789)

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **url** (string) - Full VNC URL to open in a browser
- **wsUrl** (string) - WebSocket URL for noVNC client connections
- **token** (string) - Authentication token for the VNC session
- **expiresAt** (string) - ISO 8601 timestamp when the URL expires

#### Response Example
```json
{
  "url": "https://preview-sandbox-id.pit-1.try-eu.daytona.app/vnc.html",
  "wsUrl": "wss://preview-sandbox-id.pit-1.try-eu.daytona.app/vnc.html",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2024-01-16T10:30:00Z"
}
```
```

--------------------------------

### Configure Frontmatter Fields

Source: https://docs.firebender.com/api-reference/rules

Individual YAML frontmatter configuration examples for rule files, including description, glob patterns, and the alwaysApply flag.

```yaml
description: Threading and coroutine guidelines
```

```yaml
globs: "*.kt, *.kts"
```

```yaml
alwaysApply: true
```

--------------------------------

### Define Situational Rules with Glob Patterns (Markdown)

Source: https://docs.firebender.com/multi-agent/global-rules

This example demonstrates how to create rules that apply only to specific files using glob patterns in the frontmatter. The `globs` property specifies which files the rules should be associated with.

```markdown
---
description: Testing guidelines
globs: "*Kotest.kt, *Test.kt"
---

- Use Kotest framework/BDD for tests
- Mock external dependencies
- Prefer property-based testing where applicable
```

--------------------------------

### Example: Quick Explanation Command Configuration

Source: https://docs.firebender.com/api-reference/commands

This markdown snippet shows the configuration for a 'quick explain' command, intended for read-only explanations of selected code. The YAML frontmatter specifies the name, description, model, and mode, followed by instructions on how to explain code concisely.

```markdown
---
name: explain
description: Quick explanation of selected code
model: quick
mode: read
---

Explain the selected code concisely:
- What it does
- Why it's implemented this way
- Any potential issues or improvements
```

--------------------------------

### JSON Personal Ignore Patterns Example

Source: https://docs.firebender.com/api-reference/syntax

This JSON snippet shows an example of personal ignore patterns in firebender.json. These patterns are typically used for globally excluding sensitive file types or environment-specific files across all projects.

```json
{
  "ignore": [
    "**/.env",
    "**/.env.*",
    "**/credentials.json",
    "**/*.key",
    "**/*.pem"
  ]
}
```

--------------------------------

### Structure documentation with progressive disclosure

Source: https://docs.firebender.com/multi-agent/skills

Illustrates how to keep core instructions in a primary file while linking to detailed documentation for advanced topics.

```markdown
## Quick reference

[Basic instructions here]

For advanced usage, see [advanced.md](advanced.md).
For API details, see [api-reference.md](api-reference.md).
```

--------------------------------

### Reference executable scripts in documentation

Source: https://docs.firebender.com/multi-agent/skills

Demonstrates the best practice of referencing executable scripts directly in documentation rather than embedding code blocks.

```markdown
Run the analysis script: `./process.sh input.txt`
```

--------------------------------

### Define skill metadata in YAML

Source: https://docs.firebender.com/multi-agent/skills

Shows the recommended format for skill descriptions in YAML, emphasizing clarity and specific use-case triggers to improve agent performance.

```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```

--------------------------------

### Markdown: Referencing External Skill Files

Source: https://docs.firebender.com/api-reference/skills

Shows how to reference external files from a `SKILL.md` file using Markdown. This practice helps keep the main skill file concise by offloading detailed API references, advanced usage instructions, or other supplementary information to separate files.

```markdown
## Quick Start
[Brief instructions]

For detailed API reference, see [reference.md](reference.md).
For advanced usage, see [advanced.md](advanced.md).
```

--------------------------------

### Define General Project Rules (Markdown)

Source: https://docs.firebender.com/multi-agent/global-rules

This snippet shows how to define general rules for a project using a Markdown file. It includes frontmatter for configuration like `alwaysApply` and the main content defining project guidelines.

```markdown
---
alwaysApply: true
---

# Project Context

This is a food delivery app (similar to DoorDash).

Guidelines:
- Never use runBlocking
- Don't hardcode dpi
- Use `@SerializedName` for data/retrofit classes because code gets obfuscated
- Follow Material Design 3 guidelines and components
- Use Kotlin coroutines and Flow for asynchronous operations
```

--------------------------------

### Configure Database Query Agent with MCP (Markdown)

Source: https://docs.firebender.com/api-reference/agents

Sets up a 'Database Agent' with read permissions and specific MCP tools for querying databases. It includes a description and specifies a small model.

```markdown
---
name: Database Agent
description: Query and analyze database schemas
tools: read, mcp_supabase_list_tables, mcp_supabase_execute_sql
model: small
---

You are a database specialist. Help users:
- Understand database schemas
- Write efficient SQL queries
- Analyze query performance
- Suggest schema improvements
```

--------------------------------

### GET /api-reference/cloud-agents/list-available-models

Source: https://docs.firebender.com/api-reference/overview

Retrieves a list of all model identifiers compatible with Firebender Cloud Agents.

```APIDOC
## GET /api-reference/cloud-agents/list-available-models

### Description
Retrieves a list of all available AI models that can be used when launching Cloud Agents.

### Method
GET

### Endpoint
/api-reference/cloud-agents/list-available-models

### Parameters
None

### Request Example
GET /api-reference/cloud-agents/list-available-models

### Response
#### Success Response (200)
- **models** (array) - A list of available model identifier strings.

#### Response Example
{
  "models": ["claude-sonnet-4-5-20250929", "gpt-4o", "llama-3-70b"]
}
```

--------------------------------

### Reference Architecture Documentation as Rules (Markdown)

Source: https://docs.firebender.com/multi-agent/global-rules

This snippet illustrates how to use a Markdown file to define rules that reference broader architectural guidelines. It includes frontmatter to set `alwaysApply` and `globs`, and the content outlines UI and Data layer best practices.

```markdown
---
description: Android architecture guidelines
globs: "*.kt"
alwaysApply: false
---

# Android Architecture Guidelines

## UI Layer
- Use Jetpack Compose for new UI components
- Follow Material Design 3 guidelines
- Implement unidirectional data flow with ViewModels

## Data Layer
- Use Room for local database storage
- Implement Repository pattern for data access
- Use Retrofit for network operations
```

--------------------------------

### GET /agents/status

Source: https://docs.firebender.com/api-reference/get-agent-status

Retrieves the current operational status and detailed metadata for a specific cloud agent.

```APIDOC
## GET /agents/status

### Description
Retrieve the current status and details of a cloud agent. This endpoint provides real-time information regarding the agent's health and configuration.

### Method
GET

### Endpoint
/agents/status

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - The unique identifier of the cloud agent.

### Request Example
GET /agents/status?agent_id=fb-12345

### Response
#### Success Response (200)
- **status** (string) - The current state (e.g., "online", "offline", "busy").
- **uptime** (integer) - Duration in seconds the agent has been active.
- **version** (string) - The current software version of the agent.

#### Response Example
{
  "status": "online",
  "uptime": 3600,
  "version": "1.0.4"
}
```

--------------------------------

### GET /v0/agents

Source: https://docs.firebender.com/api-reference/list-agents

Retrieves a paginated list of all cloud agents owned by the authenticated user, sorted by creation date.

```APIDOC
## GET /v0/agents

### Description
List all cloud agents owned by the authenticated user, ordered by creation date (newest first).

### Method
GET

### Endpoint
/v0/agents

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of cloud agents to return (max 100). Default: 20.
- **cursor** (string) - Optional - Pagination cursor from the previous response.

### Request Example
GET /v0/agents?limit=10&cursor=fb_xyz789abc123

### Response
#### Success Response (200)
- **agents** (array) - List of agent objects.
- **nextCursor** (string) - Cursor for fetching the next page of results.

#### Response Example
{
  "agents": [
    {
      "id": "fb_abc123xyz789",
      "name": "Add README Documentation",
      "status": "RUNNING",
      "source": {
        "repository": "https://github.com/your-org/your-repo",
        "ref": "main"
      }
    }
  ],
  "nextCursor": "fb_def456ghi789"
}
```

--------------------------------

### GET /v1/recordings/{id}

Source: https://docs.firebender.com/api-reference/get-agent-status

Retrieves a time-limited presigned URL for a recorded video file generated by a debug_auto agent.

```APIDOC
## GET /v1/recordings/{id}

### Description
Retrieves a time-limited presigned URL for the video file generated after a debug_auto agent completes its task.

### Method
GET

### Endpoint
/v1/recordings/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the recording.

### Response
#### Success Response (200)
- **url** (string) - A presigned URL to download the video file.

#### Response Example
{
  "url": "https://cloud.firebender.com/v1/recordings/fb_abc123xyz789"
}
```

--------------------------------

### GET /v0/agents/{id}

Source: https://docs.firebender.com/api-reference/get-agent-status

Retrieve the current status and details of a specific cloud agent using its unique identifier.

```APIDOC
## GET /v0/agents/{id}

### Description
Retrieve the current status and details of a cloud agent.

### Method
GET

### Endpoint
/v0/agents/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier for the cloud agent. Example: `fb_abc123xyz789`

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the cloud agent.
- **name** (string) - Name for the agent.
- **status** (AgentStatus) - The current status of the agent.
- **source** (object) - Information about the source repository.
  - **repository** (string) - The GitHub repository URL.
  - **ref** (string) - Git ref (branch/tag) used as the base branch.
- **target** (object) - Information about the agent's work target.
  - **branchName** (string) - The Git branch name where the agent is working.
  - **url** (string) - VNC preview URL.
  - **prUrl** (string) - URL to view the pull request in GitHub.
  - **autoCreatePr** (boolean) - Whether a pull request will be automatically created.
- **summary** (string) - Summary of the agent's work.
- **vncUrl** (string) - Direct VNC URL for the agent's live preview.
- **vncToken** (string) - Authentication token for the VNC session.
- **recordingUrl** (string) - URL to the emulator screen recording.

#### Response Example
```json
{
  "id": "fb_abc123xyz789",
  "name": "Add README Documentation",
  "status": "RUNNING",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "firebender/abc123xyz789",
    "url": "https://preview-sandbox-id.pit-1.try-eu.daytona.app/vnc.html",
    "prUrl": "https://github.com/your-org/your-repo/pull/1234",
    "autoCreatePr": false
  },
  "summary": "Added README.md with installation instructions and usage examples",
  "vncUrl": "https://preview-sandbox-id.pit-1.try-eu.daytona.app/vnc.html",
  "vncToken": "eyJhbGciOiJIUzI1NiIs...",
  "recordingUrl": "https://example.com/recording.mp4"
}
```

#### Error Responses
- **400**: Invalid request - bad agent ID format.
- **401**: Unauthorized - invalid or missing API key.
- **403**: Forbidden - insufficient permissions.
- **404**: Agent not found or access denied.
- **429**: Rate limit exceeded.
- **500**: Internal server error.
```

--------------------------------

### Migrate Command Configuration

Source: https://docs.firebender.com/api-reference/commands

Demonstrates the transition from a centralized JSON configuration to the modular .mdc file format. The legacy JSON structure is replaced by individual files containing YAML frontmatter for command metadata.

```json
{
  "commands": [
    {
      "name": "create pr",
      "path": "commands/pr.md",
      "mode": "write"
    }
  ]
}
```

```markdown
---
name: create pr
mode: write
---

(contents of commands/pr.md)
```

--------------------------------

### GET /analytics/user-metrics

Source: https://docs.firebender.com/api-reference/daily-usage-data

Retrieves comprehensive usage metrics for a specific user, including inline edit statistics and autocomplete performance data.

```APIDOC
## GET /analytics/user-metrics

### Description
Retrieves interaction metrics for a user, tracking inline edits and autocomplete usage patterns.

### Method
GET

### Endpoint
/analytics/user-metrics

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address of the user to retrieve metrics for.

### Request Example
GET /analytics/user-metrics?email=user1@firebender.com

### Response
#### Success Response (200)
- **inlineEditAccepts** (integer) - Number of inline edit accepts
- **inlineAcceptedLinesAdded** (integer) - Lines added through inline accepts
- **inlineAcceptedLinesRemoved** (integer) - Lines removed through inline accepts
- **autocompleteAccepts** (integer) - Number of autocomplete accepts
- **autocompleteShown** (integer) - Number of times autocomplete was shown
- **autocompleteAcceptedCharactersAdded** (integer) - Characters added through autocomplete
- **autocompleteAcceptedCharactersRemoved** (integer) - Characters removed through autocomplete

#### Response Example
{
  "inlineEditAccepts": 0,
  "inlineAcceptedLinesAdded": 23,
  "inlineAcceptedLinesRemoved": 12,
  "autocompleteAccepts": 2,
  "autocompleteShown": 6,
  "autocompleteAcceptedCharactersAdded": 237,
  "autocompleteAcceptedCharactersRemoved": 0
}
```

--------------------------------

### POST /v2/organization/daily-usage-data

Source: https://docs.firebender.com/api-reference/daily-usage-data

Retrieve daily usage statistics for your organization. This endpoint requires a start and end date in Unix timestamp format.

```APIDOC
## POST /v2/organization/daily-usage-data

### Description
Retrieve daily usage statistics for your organization.

### Method
POST

### Endpoint
/v2/organization/daily-usage-data

### Parameters
#### Query Parameters
None

#### Request Body
- **startDate** (integer) - Required - Unix timestamp in milliseconds for the start date.
- **endDate** (integer) - Required - Unix timestamp in milliseconds for the end date.

### Request Example
```json
{
  "startDate": 1752227938831,
  "endDate": 1752227938831
}
```

### Response
#### Success Response (200)
- **data** (array) - Array of daily usage records.
- **period** (object) - Object containing the requested start and end dates.
  - **startDate** (integer) - Requested start date timestamp.
  - **endDate** (integer) - Requested end date timestamp.

#### Response Example
```json
{
  "data": [
    {
      "date": 1752192000000,
      "ideOpened": true,
      "agentPrompts": 4,
      "agentAccepts": 3,
      "agentFullAccepts": 1,
      "agentAcceptedLinesAdded": 134,
      "agentAcceptedLinesRemoved": 37,
      "inlineEdits": 10
    }
  ],
  "period": {
    "startDate": 1752227938831,
    "endDate": 1752227938831
  }
}
```

#### Error Responses
- **400 Bad Request**: Invalid request - bad date parameters.
- **401 Unauthorized**: Invalid or missing API key.
- **403 Forbidden**: Insufficient permissions.
- **429 Too Many Requests**: Rate limit exceeded.
- **500 Internal Server Error**: Server error.
```

--------------------------------

### POST /v0/agents/{id}/followup

Source: https://docs.firebender.com/api-reference/add-followup

Add a followup instruction to an existing cloud agent. This endpoint handles both running and stopped agent states, creating continuation agents when necessary.

```APIDOC
## POST /v0/agents/{id}/followup

### Description
Add a followup instruction to an existing cloud agent. If the agent's sandbox is still running, the followup is sent directly to it (200). If the sandbox has stopped (agent is FINISHED), a new continuation agent is created on the same branch with the previous work preserved (201).

### Method
POST

### Endpoint
/v0/agents/{id}/followup

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier for the cloud agent

#### Request Body
- **prompt** (object) - Required - The task or instructions for the agent to execute
  - **text** (string) - Required - The task or instructions for the agent to execute
  - **images** (array) - Optional - Optional array of base64 encoded images (max 5)

### Request Example
```json
{
  "prompt": {
    "text": "Add a README.md file with installation instructions",
    "images": []
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the cloud agent
- **message** (string) - Description of the action taken
- **vmResponse** (object) - Response from the agent's sandbox (if available)

#### Success Response (201)
- **id** (string) - Unique identifier for the new continuation agent
- **message** (string) - Description of the action taken
- **continuationOf** (string) - ID of the original agent that this continues

#### Error Response (400, 401, 403, 404, 429, 500)
- **error** (object) - Details about the error
```