> 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`.

# Workflows and Project Chat

Project chats combine a **project agent**, optional **workflow buttons**, file attachments, and horizon tools.

## Architecture

```
Project agent prompt (default brain)
  + optional workflow_prompt_id (button click)
  + project user summary (injected context)
  + global tool allowlist (horizon tools + web search)
  → LLM with tool calls → reply (markdown by default)
```

## Project agent prompt

One prompt per project (`category: project`, id = project UUID). Edit the agent **system message** in **Project Settings → Agent Settings** — this is the project’s LLM instructions, not **Settings → System** (instance embedding/API config). See [settings-system-vs-agent](settings-system-vs-agent.md). Controls default behavior for all sessions unless a workflow overrides instructions for a single message.

## Workflow catalog

1. Create prompts under **Settings → Prompts → Project chat button catalog**.
2. Set workflow system message, user prompt, model, and explicit **tools** list.
3. In **Project Settings**, add and order workflow buttons.
4. Users click a button beside **Attach**; the message includes `workflow_prompt_id`.

Workflow tools intersect with the project global allowlist — you cannot grant tools the project does not already allow.

## Tool allowlists

| Layer | Effect |
| --- | --- |
| Project global | All horizon search/analytics + active web search + email draft + Deep Research tools (default chat) |
| Workflow prompt `tools` | Subset for that button’s messages (configured on the catalog prompt) |

Project Settings → Agent Settings includes a **Project tools** allowlist (optional). When set, chat and workflow buttons are limited to those tools (workflow lists are intersected with the project list). Tool chain steps must also appear on the project allowlist. Email draft / locked-record / embedding helpers are only kept if they are on the explicit allowlist.

## Example: Deep Research button

Create a workflow catalog prompt whose system message tells the model to call `start_deep_research` with the user’s objective (optional `mode` such as `competitive_analysis`), return the `job_id`, and not invent a full report. Users can follow the run under **Research**, or ask the agent to call `get_deep_research_status` / `get_deep_research_report` with that `job_id` later. Full start → poll → report flow: [research](research.md) (section *From project chat / workflow buttons*).

## Attachments and markdown

- **Attach** sends files with the message (PDF, images, text).
- Agent replies render as Markdown by default; disable under **Settings → User → Appearance**.

## Conversation ingest

**Ingest** on an agent message opens a modal to write structured data into ingestion groups. Useful for capturing agent-generated tables or facts into horizon data. See [projects](projects.md).

## Example: AR collection email drafts

Create a workflow catalog prompt that:

1. Uses horizon search/analytics tools to find unpaid or past-due accounts.
2. Drafts one polite or escalating email per recipient (tone by aging: reminder → firm → final notice).
3. Calls `save_email_draft` for each recipient so drafts are stored in Zagger.
4. Only calls `save_email_draft_to_gmail` when the user explicitly asks to push to Gmail; otherwise offer markdown export via `export_email_draft_md`.

See [email-drafts](email-drafts.md) for API details and Google OAuth requirements.

## Product Help workflow

Built-in **Ask Zagger** uses the Product Help project, `product_docs_search` tool, and a dedicated workflow prompt. Answers are grounded in ingested documentation from `public/docs`.