> ## Documentation Index
> Fetch the complete documentation index at: https://deck.promptphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Deck by PromptPHP helps you organise your AI Agents instructions as structured, version-controlled files, making it easy to iterate, compare, and activate prompt versions across your Laravel / PHP application.

It provides variable interpolation, performance tracking, A/B testing, and optional seamless integration with the [Laravel AI SDK](https://laravel.com/docs/ai-sdk).

## Quick start

Get up and running with Deck in minutes.

<Card title="Installation guide" icon="rocket" href="/getting-started/installation" horizontal>
  Install, configure, and verify Deck in your Laravel project.
</Card>

## Quick usage

### Creating a prompt

After installing (<a href="/getting-started/installation" target="_blank">installation guide</a>), use the Artisan command to create a versioned prompt:

```bash theme={null}
php artisan make:prompt order-summary
```

This creates the following structure:

```
resources/prompts/
└── order-summary/
    ├── v1/
        └── system.md
    └── metadata.json
```

Edit `resources/prompts/order-summary/v1/system.md` with your prompt content. Use `{{ $variable }}` syntax for dynamic values:

```markdown theme={null}
You are a {{ $tone }} customer service agent.
Summarise the following order for the customer: {{ $order }}.
```

### Using a prompt

Load and render prompts with the `Deck` facade:

```php theme={null}
use PromptPHP\Deck\Facades\Deck;

// Load the active version of a prompt.
$prompt = Deck::get('order-summary');

// Render a role with variables.
$prompt->system(['tone' => 'friendly', 'order' => $orderDetails]);
// "You are a friendly customer service agent. Summarise the following order..."

// Build a messages array ready for any chat-completion API.
$messages = $prompt->toMessages(['tone' => 'friendly', 'order' => $orderDetails]);
// [['role' => 'system', 'content' => '...']]
```

### Versioning

Create a new version of an existing prompt:

```bash theme={null}
php artisan make:prompt order-summary
# Automatically creates v2, v3, etc.
```

Activate a specific version:

```bash theme={null}
php artisan prompt:activate order-summary v2

# or

php artisan prompt:activate order-summary 2
```

Or load a specific version programmatically:

```php theme={null}
$prompt = Deck::get('order-summary', 'v2');
```

### Laravel AI SDK integration

If you use the [Laravel AI SDK](https://laravel.com/docs/ai-sdk), add the `HasPromptTemplate` trait to your agents. This way, you do not need to define the `instructions()` method as it is provided automatically.

```php theme={null}
use PromptPHP\Deck\Concerns\HasPromptTemplate;

class OrderAgent extends Agent
{
    use HasPromptTemplate;

    // instructions() and promptMessages() are provided automatically.
}
```

Running `make:agent` will also auto-scaffold a matching prompt directory.

## Key features

<CardGroup cols={2}>
  <Card title="Versioned prompts" icon="layer-group" href="/core/prompts">
    Store prompts as files on disk with directory-based versioning. Load,
    render, and switch between versions effortlessly.
  </Card>

  <Card title="Prompt generator" icon="wand-magic-sparkles" href="/core/make-prompt">
    Scaffold versioned, role-based prompt structures with the `make:prompt`
    Artisan command.
  </Card>

  <Card title="Variable interpolation" icon="code" href="/core/prompts#variable-interpolation">
    Use `{{ $variable }}` syntax in prompt templates for dynamic content
    rendering.
  </Card>

  <Card title="AI API messages" icon="message" href="/core/prompts#building-messages-for-ai-apis">
    Convert prompts to messages arrays ready for OpenAI, Anthropic, and
    other chat-completion APIs.
  </Card>

  <Card title="Laravel AI SDK" icon="robot" href="/integrations/ai-sdk">
    First-class integration with Laravel AI SDK — auto-scaffolding, traits,
    and middleware.
  </Card>

  <Card title="Performance tracking" icon="chart-line" href="/advanced/tracking">
    Log executions with token usage, latency, cost, and feedback for A/B
    testing and monitoring.
  </Card>
</CardGroup>

## Explore the docs

<CardGroup cols={3}>
  <Card title="Configuration" icon="gear" href="/getting-started/configuration">
    Customise caching, tracking, and file settings.
  </Card>

  <Card title="Artisan commands" icon="terminal" href="/core/commands">
    Five commands for managing prompts from the CLI.
  </Card>

  <Card title="Testing" icon="flask-vial" href="/advanced/testing">
    Strategies and examples for testing prompts.
  </Card>
</CardGroup>