The Context Builder is a dedicated chat where your team creates and edits the components that live in your Context Layer — metrics, entities, segments, dimensions, skills, and product memory items. The Builder treats every change as part of a single draft version of your catalog: you take the lock on the Context Layer, make your edits, audit the updates, and deploy a new version when you’re ready. The Builder’s separate chat is accessed from the Context Builder entry in the sidebar or from any Edit or Add action in the Semantic Catalog. Built-in skills likeDocumentation Index
Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt
Use this file to discover all available pages before exploring further.
/metric, /entity, /segment, /skill, and /product-memory — with subcommands such as add, edit, and delete — are the skills that allow you to build and maintain every component of your Context Layer.
Building requires write access to the Context Layer — Admins and Analyst Contributors by default. See User Management and Roles for the full breakdown.
The Build Cycle
Every set of changes follows the same cycle:- Lock — Take ownership of the catalog so no one else edits at the same time
- Build — Create, edit, or delete components in the Builder chat
- Test — Use Ask Anything to verify your changes produce the expected answers
- Audit — Run
/audit-changesto catch broken references, duplicates, and gaps - Deploy — Publish your draft as a new version for everyone
The Lock
Editing the Context Layer is a single-writer operation — only one user can hold the draft at a time. When you click Start Editing, ClarityQ acquires the lock for the entire catalog (not for an individual component). While the lock is yours:- You can run as many Builder commands as you want — each one edits the same draft.
- Other users are unaffected — they continue using the published version as normal. If someone else tries to start editing, they’ll see that the Context Layer is locked, who holds the lock, and when the editing session started.
Only one Builder chat can be active at a time. Starting a new Builder chat while another is open prompts you to switch — past chats stay in your history.
Drafts and Versioning
Each change you make in the Builder lands on a draft version of your catalog. By default the catalog has a single published version that everyone uses; while a draft is open, a second state exists alongside it:| State | Who sees it |
|---|---|
| Published | Everyone — what the agent uses for Ask Anything answers. |
| Draft | Only you (the lock holder) — visible across the entire product, including Ask Anything, so you can test your changes before deploying. |
- New Build — Start another Builder chat against the same draft.
- Test in Chat — Open an Ask Anything chat that uses your draft instead of the published catalog. Ask the questions your changes are meant to answer — for example, after redefining your DAU metric, ask “what was DAU last week?” — and make sure the agent picks up your new definition and returns what you expect. Other people’s chats keep using the published version, so your testing stays isolated.
- View changes — See a detailed list of all changes between the current published version and your draft (created, modified, and deleted components).
- Discard — Throw the draft away. Every edit you made in this session is removed and the catalog snaps back to its current published version. The lock is released so someone else can start a new draft. There’s no undo — once a draft is discarded it can’t be recovered.
- Deploy — Promote the draft to a new published version of the catalog. The version number increments, your changes go live for everyone in your organization, and the lock is released. ClarityQ also snapshots the change set with an auto-generated description so the version history records what changed.
The Pre-Deploy Audit Gate
When you press Deploy, ClarityQ checks whether your draft has been audited since its last edit. If not, you see a prompt asking you to either run an audit first or deploy without one. The audit (/audit-changes) is a separate Builder skill that focuses on the changes introduced in your current draft — looking for broken references, dead tables, duplicate definitions, orphaned components, and similar gaps. Running it before deploying catches mistakes that would otherwise reach every user.
Version History and Rollback
To reach the version history, click the All versions link that appears at the top of the Semantic Catalog, Skills, and Product Memory screens. The page lists every deployed version with its timestamp, author, and the auto-generated description for the change set. Each row offers one or more actions:- View Changes — Available on every version. Opens a detailed list of changes between that version and the one immediately before it, showing every component created, modified, or deleted in that release. Use it to audit a specific deploy — “what changed when we shipped v4?”
- Compare to Current — Available on any version that isn’t the current published one. Opens a diff between that version and the currently published version, so you can see the cumulative drift since a known good state — “what’s changed in the catalog since v3?”
- Rollback — Available on any version that isn’t the current published one. Immediately restores the catalog to that version’s state and publishes it as a new version. Rolling back doesn’t erase the versions in between — the history is append-only.