# Prompt definition

Generic prompt infrastructure for Transcribe (Prompt Hub). Detection, OCR, and cleanup prompts are addressable as `PromptDefinition` values.

## Identity

- Built-in prompts are identified by `(prompt_id, version)` strings.
- Custom prompts use `prompt_id` under a namespace (e.g. `custom/<slug>`) with monotonic `version`.
- Workspace **overrides** of built-ins keep the same `prompt_id` and bump `version`.
- Prompt identity participates in detection cache identity and OCR job `prompt_sha256` freeze.

## PromptDefinition (logical shape)

| Field | Required | Notes |
|-------|----------|-------|
| `format` | yes (persisted) | `"transcribe.prompt-definition"` |
| `schema_version` | yes (persisted) | `1` |
| `prompt_id` | yes | Stable identifier |
| `version` | yes | Bump on wording or schema change |
| `title` | yes | Catalogue label |
| `description` | no | Human-readable summary |
| `system_prompt` | yes | Fixed instructions; **never** contains template slots |
| `user_template` | yes | Template with data-slot placeholders only |
| `input_mode` | yes | `text` \| `vision` \| `hybrid` |
| `response_schema_id` | yes | Schema id, or `free_text` for OCR/cleanup |
| `prompt_family` | yes | `ocr` \| `cleanup` \| `detection` \| `custom` |
| `model_requirements` | yes | `{capability: text\|vision}` |
| `default_generation_options` | no | Merged with workspace LLM knobs at run time |

## Rendering boundary (normative)

Notebook/page content is **untrusted data**. Renderers must:

1. Keep `system_prompt` free of notebook-derived strings and template slots.
2. Substitute data slots in `user_template` only.
3. Wrap substituted content in explicit delimiters for detection content slots.
4. Never treat notebook text as instructions.

## Storage

| Location | Role |
|----------|------|
| Built-in registry | Code (`prompt_engine.registry` + OCR/cleanup adapters) |
| Workspace custom | `data/config/prompts/custom/<slug>.json` |
| Workspace overrides | `data/config/prompts/overrides/<prompt_id>.json` |
| Project `prompts/` | Optional project-local overrides |

Persisted files use `format: transcribe.prompt-definition` / `schema_version: 1`.

## Resolution order

Project override → workspace override → workspace custom → code builtin (including OCR/cleanup adapters).

## Versioning policy

When `version` changes, prior results remain provenance-addressable. Freshness semantics compare `(prompt_id, version)` in detection cache identity; stale results are marked, not silently upgraded. OCR jobs freeze exact rendered text SHA at job start. Builtin OCR ids include `faithful_markdown`, `faithful_text`, and `free_ocr` (DeepSeek-OCR recipe). Model-name recipes may select `free_ocr` at JobPlan freeze; a notebook custom prompt still wins — [ocr_model_recipes.md](../runtime/ocr_model_recipes.md).