From 453ab3bba6a71418b7b3f4952b141006923520d6 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 12:28:06 +0000 Subject: [PATCH] docs: correct activation, nullable user_prompt and name validation details (follow-up to #18) --- docs/advanced/api-reference.mdx | 25 ++++++++++++++++++------- docs/advanced/tracking.mdx | 2 +- docs/core/commands.mdx | 2 +- docs/core/make-prompt.mdx | 2 ++ docs/core/prompts.mdx | 2 +- 5 files changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/advanced/api-reference.mdx b/docs/advanced/api-reference.mdx index 9869270..9276330 100644 --- a/docs/advanced/api-reference.mdx +++ b/docs/advanced/api-reference.mdx @@ -35,7 +35,7 @@ Load a prompt by name and optional version. Accepts `2`, `'2'`, or `'v2'`. If ve Caches the loaded prompt if caching is enabled. -**Throws:** `PromptNotFoundException` if the prompt does not exist. `InvalidVersionException` if the specified version does not exist. +**Throws:** `InvalidPromptNameException` if the name is not a valid prompt name. `PromptNotFoundException` if the prompt does not exist. `InvalidVersionException` if the specified version does not exist. ```php $prompt = $manager->get('order-summary'); // active version @@ -70,7 +70,7 @@ Activate a specific version of a prompt. Returns `true` on success. Accepts the same version formats as `get()`, so `2`, `'2'`, and `'v2'` are equivalent. A version that cannot be parsed throws `InvalidVersionException`. -- **With tracking enabled:** Updates the `prompt_versions` database table. +- **With tracking enabled:** Records the version as active in the `prompt_versions` table, inserting a row if the version has not been activated before, and also writes `metadata.json`. - **Without tracking:** Writes to `metadata.json` in the prompt directory. ```php @@ -316,7 +316,7 @@ Handle the `CommandFinished` event. Only acts on successful `make:agent` command | `name` | `string` | — | Prompt name. | | `version` | `int` | `integer` | Version number. | | `system_prompt` | `string\|null` | — | System prompt content. | -| `user_prompt` | `string` | — | User prompt content. | +| `user_prompt` | `string\|null` | — | User prompt content. | | `metadata` | `array\|null` | `array` | Version metadata. | | `is_active` | `bool` | `boolean` | Whether this is the active version. | @@ -365,10 +365,21 @@ Thrown when a prompt directory does not exist. Thrown when a requested version does not exist or no versions are found. -| Factory Method | Description | -| --------------------------------------------- | ----------------------------------------------------------------------------------------- | -| `forPrompt(string $name, int $version): self` | Creates exception with message: `"Version {version} for prompt [{name}] does not exist."` | -| `noVersions(string $name): self` | Creates exception with message: `"No versions found for prompt [{name}]."` | +| Factory Method | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| `forPrompt(string $name, ?int $version): self` | Creates exception with message: `"Version {version} for prompt [{name}] does not exist."` | +| `noVersions(string $name): self` | Creates exception with message: `"No versions found for prompt [{name}]."` | +| `unparseable(string $name, string\|int $version): self` | Creates exception with message: `"Invalid version [{version}] for prompt [{name}]. Use a positive number like [1] or [v1]."` | + +### InvalidPromptNameException + +`PromptPHP\Deck\Exceptions\InvalidPromptNameException` + +Thrown when a prompt name contains characters other than letters, numbers, dots, dashes, and underscores, or begins with a dot. + +| Factory Method | Description | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `named(string $name): self` | Creates exception with message: `"Prompt name [{name}] is not valid. Names may contain letters, numbers, dots, dashes, and underscores, and may not begin with a dot."` | ### ConfigurationException diff --git a/docs/advanced/tracking.mdx b/docs/advanced/tracking.mdx index 9ec72ae..e363e68 100644 --- a/docs/advanced/tracking.mdx +++ b/docs/advanced/tracking.mdx @@ -68,7 +68,7 @@ Stores prompt version records and tracks which version is active. | `name` | `string` | No | The prompt name (e.g. `order-summary`). | | `version` | `unsigned int` | No | The version number (e.g. `1`, `2`, `3`). | | `system_prompt` | `text` | Yes | The system prompt content. | -| `user_prompt` | `text` | No | The user prompt content. | +| `user_prompt` | `text` | Yes | The user prompt content. | | `metadata` | `json` | Yes | Version metadata as JSON. | | `is_active` | `boolean` | No | Whether this version is the active version. Default: `false`. | | `created_at` | `timestamp` | Yes | Creation timestamp. | diff --git a/docs/core/commands.mdx b/docs/core/commands.mdx index c33efc2..3785fec 100644 --- a/docs/core/commands.mdx +++ b/docs/core/commands.mdx @@ -177,7 +177,7 @@ Version 2 of prompt [order-summary] activated. ### How it works -- **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. +- **With database tracking enabled**: Records the version in the `prompt_versions` table. It sets `is_active = false` on all versions for that prompt, then marks the specified version active, inserting a row if that version has not been activated before. It also writes the `active_version` key to `metadata.json`. - **Without tracking**: Writes the `active_version` key to the prompt's root `metadata.json` file. ### Error handling diff --git a/docs/core/make-prompt.mdx b/docs/core/make-prompt.mdx index d51c62d..a53048c 100644 --- a/docs/core/make-prompt.mdx +++ b/docs/core/make-prompt.mdx @@ -315,6 +315,8 @@ All prompt names are automatically converted to **kebab-case** for consistent di This normalisation applies to both the prompt name and any extra role names provided via `--role`. +After normalisation, the prompt name must contain only letters, numbers, dots, dashes, and underscores, and may not begin with a dot. Directory separators are not converted, so a name such as `Support/Reply` fails with an error instead of creating a nested prompt. + ## Configuration The command respects the following values from `config/deck.php`: diff --git a/docs/core/prompts.mdx b/docs/core/prompts.mdx index 97d81e1..7023738 100644 --- a/docs/core/prompts.mdx +++ b/docs/core/prompts.mdx @@ -355,7 +355,7 @@ Deck::activate('order-summary', 'v2'); 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. It sets `is_active = false` on all versions of that prompt, then `is_active = true` on the specified version. +**When database tracking is enabled**, this records the version in the `prompt_versions` table. It sets `is_active = false` on all versions of that prompt, then marks the specified version active, inserting a row if that version has not been activated before. It also writes the `active_version` key to `metadata.json`. **When tracking is disabled**, it writes the `active_version` key to the prompt's root `metadata.json` file.