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

# Projects

Projects are chat workspaces scoped to your active horizon. Each project has sessions (chats), an agent prompt, optional workflow buttons, and per-user project summary context. Open **Projects** from the main nav to create or browse projects.

## Projects vs horizons

| Concept | What it is |
| --- | --- |
| **Horizon** (suffix) | Data instance: ingestion groups, entries, tools, prompts, views |
| **Project** | Collaboration space for AI chat; uses horizon tools and data at runtime |

Switch horizon under **Settings → User → Active Horizon**. Projects list shows projects for the current horizon.

## Creating a project

1. **Projects → New Project**.
2. Enter **name** and optional **description**.
3. Choose **Public** (all horizon users) or **Private** (owner only).
4. Optionally set an initial **Opening message** (shown on the new-chat / project load screen) and **Agent Settings** system message.
5. Save. A project agent prompt (`category: project`) is created with the project id.

## Project settings

Open from the project sidebar header (**Project settings**) or `/p/{projectId}/settings`. The **owner** can change settings; **admins / superadmins** can also edit most project settings. Archive / restore is **owner-only**.

**Important:** *Project Settings → Agent Settings* is **not** the same as *Settings → System* (instance System Settings). Agent Settings control the chat agent for **this project only**. Settings → System is deployment-wide infrastructure (embedding model, system API keys). See [settings-system-vs-agent](settings-system-vs-agent.md).

### Basics

- **Name** and **description** — must be unique name across projects. Description is list metadata only.
- **Horizon** — shown when you open settings for an existing project. Tools and data for this project come from that suffix. Headless auto-projects often live on the integration’s default horizon, which can differ from your **Settings → User → Active Horizon**.
- **Opening message** (project load message) — text shown on **Start a new chat** when the project is opened with no session selected. Optional markdown. Leave blank for the default hint. This is **not** sent to the LLM; it is only UI copy (and the same `opening_description` field on the Headless API). Use **Agent system message** for model instructions.
- **Visibility** — public vs private.
- **Archive** — owner can archive to hide the project from others’ default lists while keeping data; restore when ready. Use **Show archived projects** on the Projects page to find archived projects. (To hide a single chat without archiving the project, see **Archiving chats** below.)

### Project load message

When a user opens a project home (`/p/{projectId}`) without a chat selected, Zagger shows a **Start a new chat** screen:

1. If **Opening message** is set, that text is shown above the composer (markdown follows Settings → User → Appearance).
2. If it is blank, the default is: “Type a message below to create a new session for this project.”
3. The first send creates a session; later visits to an existing chat do *not* show this message again.

Headless and embed clients should do the same: read `opening_description` from project metadata and render it only on the new-chat surface. Do not prepend it to chat `content`. Details: [headless](headless.md).

### Agent settings

*Location: Project settings dialog → **Agent Settings** section.* This configures the **project chat agent**, not the Zagger instance.

- **Agent system message** — LLM instructions (system prompt) for every chat in this project. Despite the name “system message”, this is **not** Settings → System.
- **Chat model** — not chosen here. Chat uses your **Settings → User → Active model** (and provider keys).
- **Project tools** — optional allowlist of horizon tools (search, filter, HTTP, entry update, tool chains, schedulers, etc.) plus platform helpers. Default is all tools on the project horizon. **Edit tools** opens a dialog with search, type filter, and current-horizon vs global scope; **Use these tools** saves the allowlist, **Cancel** discards. Workflow button tools are intersected with this list. Tool chain steps must also be on the allowlist.

### Workflow buttons

Link catalog prompts (`project_chat_catalog`) to show task-specific buttons beside **Attach** in chat. Order matters — use move up/down in settings. Define workflows under **Settings → Prompts → Project chat button catalog**. See [workflows](workflows.md).

## Project summary

**Project summary** (`/p/{projectId}/summary`) stores per-user, per-project context injected into the agent system prompt across sessions.

- **Content** — free-text notes, decisions, glossary.
- **Max context tokens** — cap how much summary is injected (default 4000).
- **Public summary** — when enabled, other users on the project see your summary in their agent context.
- **Submit to model** — ask the LLM to distill recent chat activity into the summary field (review before saving).

## Sessions and chat

> **Embed before significant chat or workflow use.**
> If horizon data was ingested or synced after the last embedding, search tools return incomplete results.
> Run **Initiate Embedding** (Horizon → Data Embeddings or Settings → Tools) and wait for
> **Ready** before relying on LLM answers that need your data. Projects show a warning when
> ingestion is newer than the last embed. See [tools](tools.md).

- Each project has many **sessions** (chats). Create from the project home or sidebar.
- Attach files, use workflow buttons, toggle markdown rendering in **Settings → User → Appearance**.
- **Ingest** on an agent message opens conversation ingest: pick ingestion groups (planes), preview gap-filled rows, apply to horizon data. See below.

### Archiving chats

There is no permanent delete for chats in the UI. Use **Archive** instead — it removes the chat from the default sidebar list (close enough to deleting for day-to-day cleanup) while keeping the session and messages in the database.

- **Archive a chat** — open the session, then choose **Archive chat** in the chat header. Confirm when prompted. You return to the project home and the chat no longer appears in the normal Sessions list.
- **Find an archived chat again** — in the project sidebar under Sessions, enable **Show archived chats**. Archived sessions appear with an archived badge so you can reopen them.

Archiving a **project** (Project settings → Archive) is separate: it hides the whole project from other users’ default lists. Archiving a **chat** only hides that session inside the project.

## Conversation ingest (chat → data)

On agent replies, **Ingest** lets you promote conversation content into ingestion group entries:

1. Select target ingestion group(s) tied to the project agent or workflow tools.
2. Review the LLM-generated plan (fields and rows).
3. Toggle fields/rows, modify via natural language, then **Apply** or cancel.

Applied rows go through normal entry creation (review rules still apply unless the group auto-approves). This is separate from **reingestion** of external sources — it adds structured data from chat.

## Reingestion (data horizon)

**Reingestion** applies to **ingestion groups**, not project settings. When spreadsheet columns, API mapping, or folder rules change:

- Run **Ingest** again with **sync** mode to update matched rows.
- Or **Wipe** group data in Settings → Ingestion and pull fresh.
- **Always** re-run **Initiate Embedding** on linked search tools after ingest or sync (not only after “large” changes). New rows are invisible to search until embedded.

Full steps: [ingestion-groups](ingestion-groups.md) (Reingestion section).

## Built-in Product Help project

Zagger seeds a **Product Help** project wired to `product_docs_search` over ingested documentation. Open via **Help → Ask Zagger**. Do not delete if you rely on in-app help.

## Permissions

| Action | Who |
| --- | --- |
| View public project | Any user on the horizon |
| View private project | Owner and admins |
| Edit project settings | Owner, or admin / superadmin |
| Archive / restore project | Owner only |
| Archive chat (session) | Users who can open the session |
| Create sessions | Users who can see the project |