> Public product help. This page has no customer entries, projects, chat transcripts, API keys, or horizon contents.
> Reading that data requires `Authorization: Bearer` (a signed-in app session JWT, or a Headless access token).
> Do not call Supabase `/rest/v1` with a Headless JWT. Data reads go through `/casc/v1/headless/v1/rest`.

# Prompts

Prompts are reusable AI instructions stored per horizon. Manage them in **Settings → Prompts** (AI Prompt Manager). Each prompt has a category, optional page location (where it appears as a button), linked ingestion groups, tools, model settings, and message templates.

## Where prompts appear

| Section in UI | `page_location` | Typical `category` |
| --- | --- | --- |
| Ingestion Page Prompts | `main` | `main` |
| Review Page Prompts | `review` | `review` |
| Management Page Prompts | `management` | `management` |
| Project chat button catalog | `project_chat_catalog` | `project_workflow` |
| Project agent (one per project) | — | `project` (prompt id = project id) |

Horizon pages show buttons for prompts matching that page. Project settings attach catalog workflows to a specific project.

## How to build a processing prompt

1. **Settings → Prompts → Add** in the section matching where you want the button (e.g. Review).
2. Set **name** and optional **description**.
3. Link **ingestion group(s)** — scope which entries the prompt processes.
4. Write **system message** (role, constraints) and **prompt** template (task). Use placeholders like `{{raw.field}}` — see [prompt-templating](prompt-templating.md).
5. Choose **model** and **temperature**.
6. Optional: attach **tools** (search/analytics) for agentic processing.
7. Define **response format** / output keys if the prompt writes canonical output fields. Optional: attach a **YUML** template for formatted HTML — see [yuml](yuml.md).
8. Save; button appears on the matching Horizon page for that group.

## How to build a project workflow prompt

1. Add prompt under **Project chat button catalog** (`project_chat_catalog`).
2. Set workflow system message and user prompt (task instructions).
3. Restrict **tools** to the minimum needed (e.g. one docs search tool).
4. In **Project Settings**, add the workflow to **Project chat workflow buttons** and order them.
5. Users see buttons beside Attach in chat; clicking sends `workflow_prompt_id` with the message.

## Project agent prompt

Each project has a prompt row with `category: project` and `id` equal to the project UUID. Edit via **Project Settings → Agent Settings**: the UI exposes the **agent system message** (LLM instructions for all sessions in the project). Chat model comes from **Settings → User → Active model**; tools for default chat come from the project global allowlist. To restrict tools for a specific task, use a **workflow** prompt in the project chat button catalog.

**Naming note:** The field is called *System message* in Agent Settings because it is the model’s system prompt — not because it lives under **Settings → System** (instance config). See [settings-system-vs-agent](settings-system-vs-agent.md).

## Tools on prompts

Prompt tool lists intersect with the project global allowlist. For default project chat (no workflow button), the agent uses allowlisted horizon tools (search/analytics) plus web search when configured. Workflow prompts typically list explicit tools for a focused task.

## Ingestion group scope

Link prompts to groups so processing runs in context of that group's entries. Tools on the prompt should reference the same groups' fields. Mismatched group/tool configuration causes key validation errors at save time.

## Best practices

- Keep system messages stable; put step-by-step tasks in the user prompt template.
- Test from Horizon (review/management) or a test project before wide rollout.
- Version significant changes by duplicating the prompt row (delete uses normalized ids — avoid trailing spaces in prompt id).