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

# System Settings vs Agent Settings

Zagger uses the word **system** in two different places. They are *not* the same thing. This page exists because teams often mix them up when onboarding or troubleshooting.

## Quick comparison

| | **Settings → System** (Instance System Settings) | **Project Settings → Agent Settings** (Project agent prompt) |
| --- | --- | --- |
| **Where** | Main nav → **Settings → System** | Inside a project → **Project settings** (`/p/{projectId}/settings`) |
| **Scope** | Entire Zagger **instance** (all users, all horizons) | One **chat project** only |
| **Stored as** | `cascade_system_settings` key/value rows | Prompt row: `category: project`, `id` = project UUID |
| **Who edits** | **Superadmin** writes; admins can read most values | **Project owner** (and admins) |
| **Purpose** | Platform infrastructure: embedding model, shared API credentials for ingestion sources, system Google OAuth, runtime diagnostics | How the **chat agent behaves** in that project: instructions, workflow buttons, default YUML output. Separate from the project **Opening message** (UI-only load copy). |
| **Affects chat?** | Indirectly (e.g. embedding model changes search quality; API keys enable ingestion pulls) | **Directly** — the agent system message and workflows shape every reply in the project |

## Settings → System (instance System Settings)

Use this when you are configuring the **server or deployment**, not a specific chat workspace.

- **Embedding model** — which model vectorizes horizon data for search tools. Changing it requires re-embedding. Superadmin only.
- **System API credentials** — keys referenced by ingestion sources (e.g. XE.net `XE_NET_ACCOUNT_ID` / `XE_NET_API_KEY` in system settings). Used when pulling external API feeds, not when chatting.
- **System Google OAuth** — shared OAuth app for domain-wide Drive/Sheets ingestion (Settings → Admin → Google credentials). Distinct from per-user Google under Settings → User.
- **Runtime / Supabase display** — read-only debug info for operators.

**Not here:** chat instructions, project personality, workflow buttons, or per-user API keys (those live under Settings → User).

## Project Settings → Agent Settings

Use this when you want to define **how Zagger acts inside one project**.

- **System message** — the LLM *system prompt* for the project agent (role, tone, constraints). This is **not** Settings → System. It is instructions text sent to the model on every chat in the project.
- **Opening message** — not Agent Settings. It is the project load blurb on **Start a new chat**. Display-only; see [projects](projects.md).
- **Workflow buttons** — link catalog prompts so users can run one-off tasks (summarize, extract, etc.) from the chat composer.
- **Default YUML output** — optional diagram emission after agent replies.
- **Project summary** (separate page) — per-user notes injected into agent context; see [projects](projects.md).

Chat model selection comes from **Settings → User → Active model**. Project Settings → Agent Settings does not pick the model; workflow catalog prompts may set their own model for button-driven messages.

## Common mix-ups

| People say… | They usually mean… |
| --- | --- |
| “Change the system settings for the agent” | **Project Settings → Agent Settings → System message** |
| “Set the embedding model” | **Settings → System** (superadmin) |
| “Configure API keys for ingestion” | Often **Settings → System** (shared) or source config in **Settings → Ingestion**; chat keys are **Settings → User** |
| “The agent doesn’t follow our playbook” | Edit **Agent Settings system message** or add a **workflow button**, not instance System Settings |
| “Change the welcome / load text when the project opens” | **Project settings → Opening message** (not Agent Settings) |
| “Headless tools don’t match Settings → Tools” | Check the integration / sub-user **horizon** in Headless → Review; tools are that horizon’s tools, not the admin’s Active Horizon |

## Headless API note

External servers using the **Headless** API act as the integration **owner user**. Runtime keys come from that user’s Settings → User. Horizon, tools, and data come from the integration’s **default horizon** (else the owner’s active horizon when the auto-project was created) — see [headless](headless.md). **Project Settings → Agent Settings** (system message) applies to headless chat the same as UI chat. The project **Opening message** is returned as `opening_description` for embeds to show on new chat; it is not sent to the model. Instance System Settings (embedding model, system API keys) still apply at the deployment level.

## Related pages

- [projects](projects.md) — project basics, agent settings, opening / load message
- [headless](headless.md) — headless horizon binding and how embeds show the load message
- [prompts](prompts.md) — prompt categories including `project` agent rows
- [roles-and-access](roles-and-access.md) — who can edit instance System Settings
- [api-ingestion](api-ingestion.md) — when system-level API credentials are required