diff --git a/docs/advanced/tracking.mdx b/docs/advanced/tracking.mdx index a2781c8..9ec72ae 100644 --- a/docs/advanced/tracking.mdx +++ b/docs/advanced/tracking.mdx @@ -17,7 +17,7 @@ Deck by PromptPHP includes an optional database tracking system that logs prompt Tracking is entirely optional and **off by default**. Deck works fully without it. - Prompt rendering never depends on tracking. If you enable it without running the migrations, or the database becomes unreachable, Deck falls back to `metadata.json` and logs a warning once rather than failing. `Deck::track()` never throws under any circumstances — it runs after a completed, paid-for AI call. + Prompt rendering never depends on tracking. If you enable it without running the migrations, or the database becomes unreachable, Deck falls back to `metadata.json` and logs a warning once rather than failing. `Deck::track()` never throws under any circumstances, because it runs after a completed, paid-for AI call. ## Setup @@ -141,11 +141,11 @@ Deck::track('order-summary', 2, [ ]); ``` -If tracking is disabled in configuration, the `track()` method is a safe no-op — you can call it without checking configuration first. +If tracking is disabled in configuration, the `track()` method is a safe no-op. You can call it without checking configuration first. ### Automatic tracking via middleware -When using the [Laravel AI SDK integration](/integrations/ai-sdk), the `TrackPromptMiddleware` handles tracking automatically. See [AI SDK — Performance Tracking Middleware](/integrations/ai-sdk#performance-tracking-middleware) for setup details. +When using the [Laravel AI SDK integration](/integrations/ai-sdk), the `TrackPromptMiddleware` handles tracking automatically. See [Performance tracking middleware](/integrations/ai-sdk#performance-tracking-middleware) for setup details. ### Tracked fields @@ -387,12 +387,12 @@ When tracking is enabled, `Deck::activate()` and `prompt:activate` record the ac Once a version has been activated with tracking enabled, **the database wins**. `metadata.json` is consulted only when the table holds no record for that prompt. -The practical consequence: editing `active_version` in `metadata.json`, committing it, and deploying **will not change which version is served**. Activation is environment state — it is how you promote a version in staging without touching production, and how you roll back without a deploy. The file is the bootstrap default, used until the first activation in that environment. +The practical consequence: editing `active_version` in `metadata.json`, committing it, and deploying **will not change which version is served**. Activation is environment state. It is how you promote a version in staging without touching production, and how you roll back without a deploy. The file is the bootstrap default, used until the first activation in that environment. To go back to file-based control for a prompt, delete its rows from `prompt_versions`. - The table only ever holds versions that have been **activated**. It is not a mirror of your prompt library — a version you have created but never activated has no row. The `system_prompt` and `user_prompt` columns are nullable and are written as `NULL`: Deck is file-based, and content lives on disk. + The table only ever holds versions that have been **activated**. It is not a mirror of your prompt library. A version you have created but never activated has no row. The `system_prompt` and `user_prompt` columns are nullable, and Deck writes them as `NULL` because content lives on disk. ```php diff --git a/docs/core/commands.mdx b/docs/core/commands.mdx index 69a2550..c33efc2 100644 --- a/docs/core/commands.mdx +++ b/docs/core/commands.mdx @@ -85,7 +85,7 @@ What would you like to do? With `--force`, the latest version is overwritten without prompting. -See [Creating Prompts](/core/make-prompt) for comprehensive documentation. +See [Creating prompts](/core/make-prompt) for comprehensive documentation. ## prompt:list @@ -140,8 +140,8 @@ Output: ### Notes -- If the prompts directory does not exist, a warning is displayed. -- If no prompts are found, an informational message is shown. +- If the prompts directory does not exist, the command displays a warning. +- If the command finds no prompts, it shows an informational message. - Descriptions come from the prompt's root `metadata.json`, and a version may override the shared description in its own `metadata.json`. ## prompt:activate @@ -177,12 +177,12 @@ Version 2 of prompt [order-summary] activated. ### How it works -- **With database tracking enabled**: Updates the `prompt_versions` table — sets `is_active = false` on all versions for that prompt, then `is_active = true` on the specified version. +- **With database tracking enabled**: Updates the `prompt_versions` table. It sets `is_active = false` on all versions for that prompt, then `is_active = true` on the specified version. - **Without tracking**: Writes the `active_version` key to the prompt's root `metadata.json` file. ### Error handling -If the prompt or version does not exist, an error message is displayed: +If the prompt or version does not exist, the command displays an error message: ``` Version 5 for prompt [order-summary] does not exist. @@ -335,6 +335,6 @@ php artisan prompt:test order-summary --input="Order #5678 with 3 items" ### Notes - The `--variables` option expects valid JSON. Invalid JSON produces an error: `Invalid JSON for --variables`. -- Expected variables (from `metadata.json`) are displayed as a hint, if available. -- Both the rendered system and user prompts are displayed. +- The command displays expected variables (from `metadata.json`) as a hint, if available. +- The command displays both the rendered system and user prompts. - Unmatched variables remain as placeholders in the output, making it easy to spot missing values. diff --git a/docs/core/make-prompt.mdx b/docs/core/make-prompt.mdx index 57c9e20..d51c62d 100644 --- a/docs/core/make-prompt.mdx +++ b/docs/core/make-prompt.mdx @@ -28,7 +28,7 @@ resources/prompts/ └── system.md ``` -A **system prompt** file is always created. Two `metadata.json` files are written: one at the prompt root recording the prompt's name, description, roles, and creation timestamp, and one inside the version directory recording that version alone. +The command always creates a **system prompt** file. It also writes two `metadata.json` files. The one at the prompt root records the prompt's name, description, roles, and creation timestamp. The one inside the version directory records that version alone. ### Interactive mode @@ -38,7 +38,7 @@ Run the command without any arguments to enter a fully interactive flow: php artisan make:prompt ``` -You will be guided through a series of questions: +The command guides you through a series of questions: 1. **What should the prompt be named?** — Provide a name (automatically converted to kebab-case). 2. **Briefly describe this prompt (press Enter to skip)** — An optional description stored in `metadata.json`. @@ -46,8 +46,8 @@ You will be guided through a series of questions: 4. **Would you like to create prompt files for additional roles?** — Confirm, then enter comma-separated role names (e.g. `assistant, developer`). - The interactive description and user-prompt questions are only asked when - the name argument is omitted. When passing a name directly, use the + The command only asks the interactive description and user-prompt questions + when you omit the name argument. When passing a name directly, use the `--desc`, `--user`, and `--interactive` options instead. @@ -122,7 +122,7 @@ The command writes two metadata files: one at the prompt root describing the pro | `variables` | Reserved for future use (template variable extraction). Never reset once you populate it. | | `created_at` | ISO 8601 timestamp of when the **prompt** was first created. | -Any other keys you add by hand are preserved — including `active_version`, so **scaffolding a new version never changes which version your application serves**. When another version is active, the command tells you how to promote the one you just created: +The command preserves any other keys you add by hand, including `active_version`. **Scaffolding a new version never changes which version your application serves**. When another version is active, the command tells you how to promote the one you just created: ``` Version 2 of the [order-summary] prompt has been created successfully with the following roles: system. @@ -143,13 +143,13 @@ Run `php artisan prompt:activate order-summary v2` to make v2 live. } ``` -Add your own keys here to override prompt-level metadata for a single version — see [Metadata](/core/prompts#metadata) for how the two files merge. +Add your own keys here to override prompt-level metadata for a single version. See [Metadata](/core/prompts#metadata) for how the two files merge. ## Roles ### System role (default) -A `system.md` file is **always** created. This is the primary prompt file and represents the system-level instructions for your AI agent. No flag is needed: +The command **always** creates a `system.md` file. This is the primary prompt file and represents the system-level instructions for your AI agent. No flag is needed: ```bash php artisan make:prompt code-reviewer @@ -176,7 +176,7 @@ php artisan make:prompt code-reviewer --user # Creates: system.md + user.md ``` -In the interactive flow (name omitted), you are asked whether to create a user prompt via a confirmation question. +In the interactive flow (name omitted), the command asks whether to create a user prompt. The default user prompt stub contains: @@ -218,8 +218,8 @@ php artisan make:prompt code-reviewer -i ``` - When `--role` values are provided explicitly, the interactive role prompt is - skipped — explicit values always take precedence. + When you provide `--role` values explicitly, the command skips the + interactive role prompt. Explicit values always take precedence. All scaffolded roles (including `system` and optionally `user`) are recorded in the `roles` array of `metadata.json`. @@ -230,7 +230,7 @@ Deck uses directory-based versioning. Each version lives in its own sub-director ### Auto-increment -When you run the command for a prompt that already has one or more versions, you are presented with a choice: +When you run the command for a prompt that already has one or more versions, the command presents a choice: ```bash php artisan make:prompt code-reviewer @@ -257,7 +257,7 @@ In non-interactive environments (CI pipelines, scripts), use `--force` (or `-f`) php artisan make:prompt code-reviewer --force ``` -If version 2 exists, `--force` overwrites `v2/` directly. It will **never** create a new version automatically — its purpose is to regenerate the latest version. +If version 2 exists, `--force` overwrites `v2/` directly. It **never** creates a new version automatically. Its purpose is to regenerate the latest version. For brand-new prompts, `--force` has no special effect; `v1/` is created as normal. @@ -288,7 +288,7 @@ your-app/ └── role-prompt.stub ``` -Published stubs **always take precedence** over the package defaults. You only need to publish the stubs you want to override — any missing stubs fall back to the package defaults. +Published stubs **always take precedence** over the package defaults. You only need to publish the stubs you want to override. Any missing stubs fall back to the package defaults. ### Using a one-off template @@ -346,7 +346,7 @@ php artisan make:prompt email-drafter --user php artisan make:prompt email-drafter --role=assistant --role=reviewer ``` -**Create a prompt with everything — user, roles, and a description:** +**Create a prompt with everything (user, roles, and a description):** ```bash php artisan make:prompt email-drafter -u --role=assistant --desc="Drafts professional emails" diff --git a/docs/core/prompts.mdx b/docs/core/prompts.mdx index a3bfb04..97d81e1 100644 --- a/docs/core/prompts.mdx +++ b/docs/core/prompts.mdx @@ -5,7 +5,7 @@ description: "Load, render, version, cache, and track AI prompts in your Laravel ## Introduction -Deck by PromptPHP provides a clean, expressive API for loading, rendering, and managing versioned AI prompts in your Laravel application. Prompts are stored as plain files on disk and organised by name, version, and role. They are accessed through the `Deck` facade. +Deck by PromptPHP provides a clean, expressive API for loading, rendering, and managing versioned AI prompts in your Laravel application. Deck stores prompts as plain files on disk and organises them by name, version, and role. You access them through the `Deck` facade. A prompt can contain multiple **roles** (system, user, assistant, developer, tool, or any custom role you define). Each role's content supports `{{ $variable }}` interpolation, and the entire prompt can be converted into a messages array ready to send to OpenAI, Anthropic, or any chat-completion API. @@ -37,11 +37,11 @@ $prompt = Deck::get('order-summary'); $prompt = Deck::get('order-summary', 2); ``` -The `get` method returns a `PromptTemplate` instance. If no version is specified, the [active version](#version-resolution-order) is resolved automatically. +The `get` method returns a `PromptTemplate` instance. If you don't specify a version, Deck resolves the [active version](#version-resolution-order) automatically. ### Prompt names -A prompt name becomes a directory path, so names are validated before they are resolved. They may contain letters, numbers, dots, dashes, and underscores, and may not begin with a dot. Anything else — most importantly a name containing `/`, `\`, or `..` — throws `InvalidPromptNameException`. +A prompt name becomes a directory path, so Deck validates names before resolving them. Names may contain letters, numbers, dots, dashes, and underscores, and may not begin with a dot. Anything else throws `InvalidPromptNameException`, most importantly a name containing `/`, `\`, or `..`. ```php Deck::get('order-summary'); // fine @@ -94,7 +94,7 @@ $prompt = Deck::get('order-summary', 1); $prompt->version(); // 1 ``` -If the version does not exist, an `InvalidVersionException` is thrown. +If the version does not exist, Deck throws an `InvalidVersionException`. ## Rendering roles @@ -102,7 +102,7 @@ Once you have a `PromptTemplate` instance, you can render any role's content wit ### Dynamic role methods -The most expressive way to render a role is to call it as a method directly on the prompt instance. This uses PHP's `__call` magic method and works for **any** role — not just `system` and `user`: +The most expressive way to render a role is to call it as a method directly on the prompt instance. This uses PHP's `__call` magic method and works for **any** role, not just `system` and `user`: ```php $prompt = Deck::get('code-reviewer'); @@ -119,7 +119,7 @@ $prompt->developer(['task' => 'review']); $prompt->tool(['name' => 'search']); ``` -When called without arguments, the content is returned with placeholders left intact: +When you call it without arguments, it returns the content with placeholders left intact: ```php $prompt->system(); // "You are a {{ $tone }} AI assistant..." @@ -135,7 +135,7 @@ $roleName = 'assistant'; $content = $prompt->role($roleName, ['context' => $history]); ``` -This is functionally identical to the magic method approach. If the role does not exist, an empty string is returned. +This is functionally identical to the magic method approach. If the role does not exist, it returns an empty string. ### Raw content @@ -159,7 +159,7 @@ $prompt->roles(); // ['system', 'user', 'assistant'] ``` -Roles are discovered automatically from the files in the version directory. Any file matching the configured extension (e.g. `.md`) becomes a role — the filename (without extension) is the role name. +Roles are discovered automatically from the files in the version directory. Any file matching the configured extension (e.g. `.md`) becomes a role. The filename (without extension) is the role name. ### Checking for a role @@ -175,8 +175,8 @@ if ($prompt->has('assistant')) { Metadata comes from two files, and `metadata` returns them merged: -1. The prompt's root `metadata.json` — shared by every version (name, description, and anything else you record there). -2. The version's own `v{n}/metadata.json` — specific to that one version. +1. The prompt's root `metadata.json`, shared by every version (name, description, and anything else you record there). +2. The version's own `v{n}/metadata.json`, specific to that one version. Version-level keys win when both files define the same key, so a version can override the shared description without affecting its siblings. @@ -185,7 +185,7 @@ $prompt->metadata(); // ['description' => 'Summarises customer orders', 'variables' => ['tone', 'input'], ...] ``` -Metadata is an associative array. If neither file exists, an empty array is returned. +Metadata is an associative array. If neither file exists, `metadata` returns an empty array. The `active_version` key is never included. It records which version your application serves, which is routing state rather than metadata about the template you loaded. Read it with `Deck::active()` instead. @@ -217,7 +217,7 @@ $messages = Deck::get('chat-agent')->toMessages([ // ] ``` -This array can be passed directly to any AI API client: +You can pass this array directly to any AI API client: ```php // OpenAI @@ -342,7 +342,7 @@ Or use the Artisan command: php artisan prompt:list --all ``` -See [Artisan Commands — prompt:list](/core/commands#promptlist) for details. +See [`prompt:list`](/core/commands#promptlist) for details. ### Activating a version @@ -353,9 +353,9 @@ Deck::activate('order-summary', 2); Deck::activate('order-summary', 'v2'); ``` -The version accepts the same formats as `Deck::get()` — `2`, `'2'`, and `'v2'` are equivalent. Anything that cannot be parsed throws `InvalidVersionException`. +The version accepts the same formats as `Deck::get()`, so `2`, `'2'`, and `'v2'` are equivalent. Anything that cannot be parsed throws `InvalidVersionException`. -**When database tracking is enabled**, this updates the `prompt_versions` table — setting `is_active = false` on all versions of that prompt, then `is_active = true` on the specified version. +**When database tracking is enabled**, this updates the `prompt_versions` table. It sets `is_active = false` on all versions of that prompt, then `is_active = true` on the specified version. **When tracking is disabled**, it writes the `active_version` key to the prompt's root `metadata.json` file. @@ -369,17 +369,17 @@ php artisan prompt:activate order-summary 2 php artisan prompt:activate order-summary v2 ``` -See [Artisan Commands — prompt:activate](/core/commands#promptactivate) for details. +See [`prompt:activate`](/core/commands#promptactivate) for details. ### Version resolution order -When you call `Deck::get('name')` without a version, the active version is resolved in this priority order: +When you call `Deck::get('name')` without a version, Deck resolves the active version in this priority order: 1. **Database** — If tracking is enabled, looks for a version marked `is_active = true` in the `prompt_versions` table for that prompt name. 2. **metadata.json** — Reads the `active_version` key from the prompt's root `metadata.json` file. 3. **Highest version** — Falls back to the highest version number found on disk (e.g. if `v1/` and `v3/` exist, version 3 is used). -If no versions exist at all, an `InvalidVersionException` is thrown. +If no versions exist at all, Deck throws an `InvalidVersionException`. ## Caching @@ -399,7 +399,7 @@ The cache key follows the pattern `{prefix}{name}.v{version}`. Prompts are cache Caching is automatically **disabled** when `APP_DEBUG=true` to ensure file changes are picked up immediately during development. -See [Configuration — Cache](/getting-started/configuration#cache) for the full reference. +See [Cache configuration](/getting-started/configuration#cache) for the full reference. ## Execution tracking @@ -418,14 +418,14 @@ Deck::track('order-summary', 2, [ ]); ``` -All fields in the data array are optional. Records are inserted into the `prompt_executions` table. If tracking is disabled, the `track` method is a safe no-op. +All fields in the data array are optional. Deck inserts records into the `prompt_executions` table. If tracking is disabled, the `track` method is a safe no-op. -See [Tracking & Performance](/advanced/tracking) for comprehensive documentation on the tracking system, database schema, and Eloquent models. +See [Tracking & performance](/advanced/tracking) for comprehensive documentation on the tracking system, database schema, and Eloquent models. When using the [Laravel AI SDK integration](/integrations/ai-sdk), the - `TrackPromptMiddleware` handles execution tracking automatically — no manual - `track()` calls needed. + `TrackPromptMiddleware` handles execution tracking automatically. You don't need + manual `track()` calls. ## Serialisation diff --git a/docs/getting-started/configuration.mdx b/docs/getting-started/configuration.mdx index 5cdd71a..f6e7945 100644 --- a/docs/getting-started/configuration.mdx +++ b/docs/getting-started/configuration.mdx @@ -5,7 +5,7 @@ description: "Set the Deck prompts path, file extension, versioning strategy, ca ## Introduction -Deck by PromptPHP ships with sensible defaults that work out of the box. Like most Laravel packages, all configuration lives in `config/deck.php` and every option can be overridden via environment variables for deployment flexibility. +Deck by PromptPHP ships with sensible defaults that work out of the box. Like most Laravel packages, Deck keeps all configuration in `config/deck.php`. You can override every option with environment variables for deployment flexibility. ## Publishing the configuration @@ -51,8 +51,8 @@ Markdown (`.md`) is the default and recommended for readability. You can change | `prompt` | `system.prompt`, `user.prompt` | - Changing the extension only affects newly generated files. Existing prompt - files are not renamed automatically. + Changing the extension only affects newly generated files. Deck doesn't + rename existing prompt files. ## Versioning strategy @@ -177,11 +177,11 @@ Tracking is **off by default**, because it needs database tables that are publis When enabled: -- **Version activation** is recorded in the `prompt_versions` table *as well as* `metadata.json`, and the table takes precedence. See [Tracking — Activation precedence](/advanced/tracking#activation-precedence). +- **Version activation** is recorded in the `prompt_versions` table *as well as* `metadata.json`, and the table takes precedence. See [Activation precedence](/advanced/tracking#activation-precedence). - **Execution tracking** via `Deck::track()` inserts records into the `prompt_executions` table. - Prompt rendering never depends on tracking. If the tables are missing or the database is unreachable, Deck falls back to `metadata.json` and logs a warning once, rather than failing. `Deck::track()` never throws at all — it runs after a completed AI call, and no analytics failure is worth discarding that response. + Prompt rendering never depends on tracking. If the tables are missing or the database is unreachable, Deck falls back to `metadata.json` and logs a warning once, rather than failing. `Deck::track()` never throws at all. It runs after a completed AI call, and no analytics failure is worth discarding that response. ### Database connection @@ -202,7 +202,7 @@ DECK_DB_CONNECTION=analytics 'scaffold_on_make_agent' => env('DECK_SCAFFOLD_ON_MAKE_AGENT', true), ``` -When the [Laravel AI SDK](https://laravel.com/docs/ai-sdk) is installed and this option is `true`, Deck automatically creates a matching prompt directory whenever you run `php artisan make:agent`. See the [AI SDK Integration](/integrations/ai-sdk) documentation for details. +When the [Laravel AI SDK](https://laravel.com/docs/ai-sdk) is installed and this option is `true`, Deck automatically creates a matching prompt directory whenever you run `php artisan make:agent`. See the [Laravel AI SDK integration](/integrations/ai-sdk) documentation for details. Set to `false` to disable automatic scaffolding: diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index c40f37a..73c2555 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -13,9 +13,9 @@ Deck by PromptPHP has the following requirements: | Laravel | `^11.0` ++ | - The `sebastian/diff` package is required and is used for the `prompt:diff` - command. It may conflict with your PHPUnit/Pest PHP installation so you may - need to upgrade these dependencies to the latest version. + Deck requires the `sebastian/diff` package for the `prompt:diff` command. + It may conflict with your PHPUnit/Pest PHP installation. If it does, + upgrade these dependencies to the latest version. ### Optional dependencies @@ -65,9 +65,9 @@ This creates two tables: | `prompt_executions` | Logs individual prompt executions with tokens, latency, cost, and feedback data. | - Database tracking is optional. Deck works fully without it as version + Database tracking is optional. Deck works fully without it. Version activation falls back to `metadata.json` files, and execution tracking is - simply disabled. + disabled. If you prefer, you may publish both the configuration and migration files by running a single command: @@ -95,7 +95,7 @@ DECK_DB_CONNECTION= # Database connection name (null for default) DECK_SCAFFOLD_ON_MAKE_AGENT=true # Auto-create prompt when running `make:agent` ``` -All environment variables are optional as sensible defaults are provided. +All environment variables are optional because Deck provides sensible defaults. ## Verifying the installation @@ -116,7 +116,7 @@ You should see the scaffolded prompt structure in `resources/prompts/hello-world ## Manual discovery -The package uses Laravel's auto-discovery, so the service provider and facade are registered automatically. No manual registration is needed. +The package uses Laravel's auto-discovery, so Laravel registers the service provider and facade automatically. You don't need to register them manually. If you have disabled auto-discovery, add the provider and facade to your `bootstrap/providers.php` (Laravel 11+) or `config/app.php`: diff --git a/docs/getting-started/introduction.mdx b/docs/getting-started/introduction.mdx index ec83599..1633b11 100644 --- a/docs/getting-started/introduction.mdx +++ b/docs/getting-started/introduction.mdx @@ -92,7 +92,7 @@ $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. +If you use the [Laravel AI SDK](https://laravel.com/docs/ai-sdk), add the `HasPromptTemplate` trait to your agents. The trait provides the `instructions()` method, so you don't need to define it. ```php use PromptPHP\Deck\Concerns\HasPromptTemplate; @@ -105,7 +105,7 @@ class OrderAgent extends Agent } ``` -Running `make:agent` will also auto-scaffold a matching prompt directory. +Running `make:agent` also auto-scaffolds a matching prompt directory. ## Key features @@ -139,8 +139,8 @@ Running `make:agent` will also auto-scaffold a matching prompt directory. other chat-completion APIs. - First-class integration with Laravel AI SDK — auto-scaffolding, traits, - and middleware. + First-class integration with Laravel AI SDK, including auto-scaffolding, + traits, and middleware. - Get Started + Get started
@@ -44,7 +44,7 @@ mode: "custom" {/* Card 1 */}
📁
-

Versioned Prompts

+

Versioned prompts

Store prompts as files on disk with directory-based versioning.

@@ -60,7 +60,7 @@ mode: "custom" {/* Card 3 */}
📊
-

Performance Tracking

+

Performance tracking

Log executions with token usage, latency, cost, and feedback for A/B testing and monitoring.

@@ -73,7 +73,7 @@ mode: "custom"

A workflow natural to you.

-

Run one artisan command, version your prompts.

+

Run one Artisan command to version your prompts.

diff --git a/docs/integrations/ai-sdk.mdx b/docs/integrations/ai-sdk.mdx index 68226ca..b61ab2b 100644 --- a/docs/integrations/ai-sdk.mdx +++ b/docs/integrations/ai-sdk.mdx @@ -16,7 +16,7 @@ All of this is entirely optional. Deck works perfectly without the AI SDK. ## Installation -Deck does **not** require the AI SDK — it's listed as a `suggest` dependency. Install it when you're ready: +Deck does **not** require the AI SDK. It's listed as a `suggest` dependency. Install it when you're ready: ```bash composer require laravel/ai @@ -38,7 +38,7 @@ Deck detects the successful command and automatically runs: php artisan make:prompt sales-coach ``` -This creates a versioned prompt directory ready for the agent to use via the `HasPromptTemplate` trait — zero extra setup required. +This creates a versioned prompt directory ready for the agent to use via the `HasPromptTemplate` trait, with zero extra setup required. ### How it works @@ -50,7 +50,7 @@ Deck registers a listener (`AfterMakeAgent`) on Laravel's `CommandFinished` even 4. Checks if the prompt already exists (skips if it does). 5. Runs `make:prompt` with the derived name. -The listener is only registered when `laravel/ai` is installed. If the prompt creation fails for any reason, it does **not** break the `make:agent` workflow — the agent is still created successfully. +The listener is only registered when `laravel/ai` is installed. If the prompt creation fails for any reason, it does **not** break the `make:agent` workflow. The agent is still created successfully. ### Example output @@ -163,7 +163,7 @@ public function promptVersion(): ?int } ``` -Return `null` (the default) to always load the active version — useful for A/B testing and gradual rollouts. +Return `null` (the default) to always load the active version. This is useful for A/B testing and gradual rollouts. ### Variable interpolation @@ -415,7 +415,7 @@ The middleware: 3. Uses the response's `then()` hook to record execution data after the response completes. 4. Calls `PromptManager::track()` with the collected data. -The middleware only tracks agents that use the `HasPromptTemplate` trait. If the agent doesn't have a `promptName()` method, the tracking is silently skipped. +The middleware only tracks agents that use the `HasPromptTemplate` trait. If the agent doesn't have a `promptName()` method, the middleware silently skips tracking. ## Accessing the template directly