# Prompt Definition Files

Prompt Definitions define **what** Scriptorium should do.

A prompt file is YAML, typically stored under `prompts/`, for example `prompts/generic.structured_events.yaml`.

## Complete Example

```yaml
id: generic.structured_events
version: "1.0.0"
default_profile: local-quality
description: Extract events from a transcript into structured JSON.

inputs:
  - name: transcript
    required: true
    content_type: text/markdown
    description: Source transcript
  - name: glossary
    required: false
    content_type: text/yaml
    description: Optional glossary context

messages:
  - role: system
    content: |
      You are a structured extraction assistant.
      Return only JSON.
  - role: user
    content_file: ./generic.structured_events.user.md

output:
  format: json
  validation_mode: json_schema
  schema_path: structured_events.schema.json
  repair_attempts: 1
```

## Available Options

- `id` (required): Prompt identifier used by `--prompt` / `prompt_id`.
- `version` (required): Prompt version string.
- `default_profile` (optional): Execution profile ID used when no explicit profile is provided.
- `description` (optional): Human-readable description.

### `inputs[]`

- `name` (required): Logical input name referenced in templates via `{{input "name"}}`.
- `required` (optional): If `true`, run fails when input is missing.
- `content_type` (optional): Metadata only (not enforced yet).
- `description` (optional): Human-readable input description.

### `messages[]`

- `role` (required): Message role such as `system` or `user`.
- `content` (optional): Inline Go-template message body.
- `content_file` (optional): Path to a template file.

Each message must set **exactly one** of `content` or `content_file`.

### `output`

- `format` (required): One of `text`, `markdown`, `json`.
- `validation_mode` (required): One of `none`, `basic`, `json`, `json_schema`.
- `schema_path` (required when `validation_mode: json_schema`): Path to JSON Schema file.
- `repair_attempts` (required): Number of bounded repair retries (`>= 0`).

## Notes and Rules

- Unknown YAML fields fail to load (strict decoding).
- `content_file` paths are resolved relative to the prompt YAML file.
- For `json_schema` validation mode, Scriptorium also sends provider-level structured output requests automatically.