Documentation by ClonePartner

Start typing to search.

Using Envoy

AI references

View Markdown

Create and manage AI reference documents that feed the assistant, edit content in the Markdown editor, and disable stale guidance.

AI references

AI references are per-deployment context documents the 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.

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.

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.