# AI references

> Source: https://docs.clonepartner.com/using/ai-references/

<!-- sources: ui/src/views/AiReferencesView.vue, ui/src/views/AiReferenceEditorView.vue, src/server/api/ai-references.ts, references/envoy/agent.md -->

# AI references

AI references are per-deployment context documents the [AI Assistant](/using/ai-assistant/) retrieves while answering questions. The list header describes them as "Instance-specific guidance merged into AI Assist context. Edit playbooks without redeploying." An enabled reference that shares its name with one of Envoy's built-in reference docs shadows the built-in version, so a deployment can hot-patch assistant guidance without a rebuild.

Creating, editing, and deleting references requires the admin or superadmin role. Changes take effect immediately — the assistant's reference cache refreshes on every save and delete.

## Screen overview

Open **AI References** from the navigation. The list shows the columns **Title**, **Slug**, **Keywords**, **Status** (an **Enabled** or **Disabled** badge), and **Updated**. **Title** and **Updated** are sortable. The toolbar has a **Search references...** field that matches title, slug, and keywords, and the header has a refresh button and a **New Reference** button.

Each row's ⋯ menu offers **Edit** and **Delete**.

<!-- screenshot: ai-references-list | AI References list with Title, Slug, Keywords, Status, and Updated columns and one Enabled and one Disabled reference -->

## To create a reference

1. Open **AI References** and select **New Reference**.
2. Fill in the metadata fields:
   - **Slug** (required) — a stable identifier, for example `salesforce-hubspot-sync`. To override a built-in reference doc, use its filename as the slug.
   - **Title** (required) — a human-readable topic name.
   - **Keywords** — comma-separated terms users are likely to ask about.
   - **Enabled for AI** — toggle whether retrieval can use this reference.
3. Write the body in the Markdown editor below the metadata fields.
4. Select **Create**. The editor switches to edit mode for the saved reference.

Slug, title, and content are all required — the server rejects a reference missing any of them.

<!-- screenshot: ai-references-editor | New AI Reference editor showing the Slug, Title, Keywords, and Enabled for AI fields above the Markdown editor -->

## To edit or delete a reference

1. Select **Edit** from a row's ⋯ menu (or open the reference from the editor URL).
2. Change the fields or content, then select **Save**.
3. To delete, open the ⋮ menu in the editor header and select **Delete**, or use **Delete** on the list row. The confirmation warns the deletion is permanent and that the AI context cache refreshes immediately.

To take a reference out of rotation without losing it, turn off **Enabled for AI** and save instead of deleting.

## When to create references

Use references for deployment-specific context the built-in docs cannot know: your naming conventions, approved runbooks, and field semantics. Two operational cautions from the reference-override contract:

- **A stale enabled reference hides upgrades.** When an enabled reference shares a slug with a built-in doc, the deployment keeps serving your copy even after the built-in doc changes. Keep such overrides in sync, or disable them so the built-in doc is the source of truth again.
- If the assistant gives outdated step or pattern suggestions after an upgrade, check this screen for an older enabled override before assuming the product docs are wrong.

References feed the assistant context; they do not change permissions. The assistant's API tools still run with the signed-in user's role.

## Related

- [AI assistant](/using/ai-assistant/) — the panel that retrieves these references
- [Server configuration](/deployment/server-configuration/) — the `ai` config block that enables the assistant
- [Lists, search, and bulk actions](/using/lists-search-and-bulk-actions/) — how search, sorting, and pagination work on this list