Clarify

Add a comment to a supported entity. ## Important notes After adding a comment, tell the user what was commented on in a friendly, conversational way.

add-comment

Cancel a calendar event. ## When to use this tool Use to cancel an event the user owns or has edit access to. For events the user is only invited to, use respond-to-calendar-event instead. ## Important notes - For recurring events, this cancels the whole series. - `notify_participants` defaults to `true` so attendees see the cancellation. - The cancellation runs as soon as this tool is called, with no confirmation step. Confirm with the user first.

delete-calendar-event

Create a new campaign (sequence) in DRAFT mode: emails, and LinkedIn steps (profile visits, connection requests, LinkedIn messages, InMails) where the workspace has LinkedIn campaigns turned on. To edit an existing campaign, use the update-campaign tool instead. 📖 **For comprehensive campaign rules and examples**: Use `read-context` with context: "campaign-docs". Before adding LinkedIn steps, also read "campaign-linkedin-steps". ## When to use this tool - When the user asks to create a new campaign, sequence, or outreach cadence - When duplicating a campaign (first fetch it with `get-campaigns`, then call this tool with its steps) ## Structuring the campaign `steps` lists the campaign's steps in send order. Each step has a `type` (`clarify:send:email`, `clarify:linkedin:visit`, `clarify:linkedin:connect`, `clarify:linkedin:message`, `clarify:linkedin:inmail`) and, after the first step, a `wait_before` in whole hours or days measured from the previous step. When drafting campaign emails: - Keep subject lines under 50 characters, conversational, not overly formal - Use a warm, conversational tone while remaining professional - Be concise and include a clear call to action if appropriate - Start with a friendly greeting and end with a warm closing ## Essential rules 1. **Waits**: The first step has no `wait_before`. Every later step needs one, relative to the step before it ("day 0, 3, 7" means waits of 3 days, then 4 days) 2. **Campaigns are Workflows**: Use this tool for campaigns, not generic workflow tools 3. Campaign steps are templates sent to multiple people 4. Use variable placeholders: {{path||fallback}} with fallback, or {{path}} without fallback 5. Only use the variables listed below (do not invent variables) 6. LinkedIn text is plain text. Email bodies are HTML ## Threading: send_as_reply Set `send_as_reply: true` on an email to thread it as a reply under the previous email (uses the prior message id and "Re: <previous subject>"). Use it when a follow-up bumps the prior email and the recipient should see it inline: - **Use** `send_as_reply: true` for content like "circling back", "just bumping this", "wanted to follow up", or any step that explicitly references the prior email's call to action without a new pitch. - **Leave it off (default)** when the step introduces a new angle, case study, or call to action; recipients triage by subject, and a fresh subject signals fresh content. Rules: - The first email always starts a new thread (`send_as_reply` must be false / omitted). - When `send_as_reply: true`, the email's `subject` is ignored at send time (the previous email's subject is reused with "Re: " prepended), but you must still provide a sensible `subject` for storage. Fallback rules (fallbacks make emails feel natural when data is missing): - ALWAYS include fallbacks for human-identifiable information: → Person names (first_name, last_name, full_name) → use "there", "Friend", etc. → Company/organization names → use "your company", "your organization", "your team" → Job titles and roles → use "your role", etc. → Location/city names → use "your area", "your region", etc. - Skip fallbacks ONLY for technical/structured data: → URLs, email addresses, phone numbers → Dates, timestamps, IDs → Numerical values and metrics ## Examples <example> Create an email campaign that sends on day 0 and day 3: { "campaign_name": "New Leads Nurture", "steps": [ { "type": "clarify:send:email", "subject": "Welcome, {{person.name.first_name||there}}", "body": "<p>Hi {{person.name.first_name||there}},</p><p>Thanks for your interest!</p>" }, { "type": "clarify:send:email", "wait_before": { "time": 3, "unit": "days" }, "subject": "Resources for {{person.company_id.name||your team}}", "body": "<p>Hey {{person.name.first_name||there}},</p><p>Here are some helpful resources...</p>" } ] } </example> ## Important notes - Audience is optional for drafts. Set `list_id` for a segment, or `recipient_ids` for specific people the user names. Never create a list just to hold specific people - Email account connection is optional for drafts (required before activating). A campaign with no email steps needs no inbox - Campaigns are created in DRAFT mode (enabled: false) - When the user wants to pace the campaign ("start 20 people a day"), set `daily_new_people_limit` where the workspace has LinkedIn campaigns turned on. Follow-up steps are never held back by it - Body should be formatted as HTML. Put each paragraph in its own <p> tag; paragraphs render with a blank line between them. Use <br/> only for a hard line break within a paragraph (e.g. between signature lines) - When describing timing to users, say "immediately" for the first step and "2 days later" or "1 hour after they accept" for later ones

create-campaign

Create an email draft in the user's connected Gmail or Outlook account for them to review, edit, and send themselves. Nothing is sent; use send-email when the user wants the message to go out now. The tool result repeats the draft's recipients, subject, and body, along with the Nylas draft ID needed to revise it. The body is plain text that will be converted to rich text blocks. Use these conventions: - Lines starting with "- " become bullet list items - Lines starting with "1. ", "2. ", etc. become numbered list items - Blank lines become paragraph breaks (consecutive blank lines are collapsed) - Lines starting with "# " or "## " become bold section labels - **bold** spans become bold text - Markdown links [label](https://example.com) and bare URLs become clickable links - Never put a placeholder or fabricated link in the body (e.g. [Recording] *(link)*, [link], or a guessed URL). Include a link only if you have the real URL from a tool result; if a referenced resource has no link available, leave it out and say in your reply that it needs to be added - Markdown horizontal rules like "---" are treated as section dividers and are not shown - Everything else becomes a regular paragraph Follow the system prompt and any activated email-writing skill for the user's preferred voice, tone, structure, and formatting judgment. If a skill gives more specific email-writing guidance that conflicts with these generic style defaults, prefer the skill. If no more specific guidance applies, write like a normal email, not a dashboard or report. Keep bodies compact and easy to scan: - Prefer short paragraphs and a small number of bullets - Use section labels only when they materially improve scanability - Use at most one blank line between sections or paragraphs - Keep section labels attached to their content; do not add a blank line immediately after a section label - Keep lists attached to the sentence or item they explain; do not add a blank line immediately before a bullet or numbered list - Avoid em dashes and dash-heavy constructions; use commas, colons, parentheses, or separate sentences instead - Do not use decorative separators, tables, code fences, blockquotes, or report-style spacing ## Threading When the user asks you to reply to an existing inbound email or thread, populate replyToMessageId so the draft threads correctly in Gmail/Outlook. Look up the value from the message_id field on a Message record (use get-records or query-data on the Message entity to find the inbound message you are replying to). Omit replyToMessageId when composing a brand new email that is not part of an existing inbound thread. replyToMessageId and replacesDraftId are different ids and must not be swapped. replyToMessageId is the short Nylas message_id of an inbound message (e.g. 19df41adc5abe23b). replacesDraftId is a Nylas draft id from a prior create-email-draft result (the "Nylas draft ID:" line). Never pass a Nylas draft id as replyToMessageId, and never pass a message_id as replacesDraftId. ## Iterating on a draft When the user is revising a draft you already created earlier in this conversation (e.g. "make it shorter", "rewrite it", "tweak the opener", "also add ..."), set replacesDraftId to the Nylas draft ID from that prior create-email-draft tool result. This updates the existing Gmail draft in place instead of leaving a duplicate behind. The Nylas draft ID appears on the "Nylas draft ID:" line of the prior tool result. Prefer this over creating a second draft whenever the user is iterating on the same email. Omit replacesDraftId when you are drafting a brand new email; for example for a different recipient, a different thread, or any message that is not a revision of the most recent draft to the same audience. ## Recipients Recipient addresses (to/cc/bcc) must come from a CRM person record. Look them up with get-records or by querying the person entity before drafting; never guess an address from a name and company domain. Any recipient that matches no person record is rejected unless you pass it in confirmedNewRecipients (only for addresses the user supplied for a brand-new contact).

create-email-draft

Create or update an agent, an autonomous AI assistant. ## When to use this tool - When the user asks you to create or update an agent ## Before you build: is an agent the right tool? Run these checks before planning. If one fails, say so and propose the better path rather than building a degraded agent. **1. Can the platform do it?** The triggers below are the only events an agent can respond to. Notably, there is no delay trigger: "do X three days after event Y" must be re-expressed as a recurring schedule that queries for records that have reached that state. Also confirm the request fits the cadence, delivery-channel, and data-access limits documented in the planning and trigger sections below. **2. Is an agent the right fit?** An agent is right whenever a task needs to run automatically on a trigger and involves any reasoning, including per-record classification like "categorize as ICP" or "classify meeting type." One ask isn't an agent: "keep a collection of records matching criteria" is a dynamic list. Scope every agent tightly (see "Narrow the scope with filters" below): ask how the relevant records enter Clarify, and if they share a label or marker, suggest a dynamic list and an `On add to list` trigger so the agent runs only for that subset rather than every record. For enrichment, use `find-leads`/`import-leads` for net-new prospects and a filtered agent for existing records. ## Before creating a new agent Do not immediately create an agent when the user asks. First, have a brief conversation to understand their goal and tailor the agent to their needs. Ask the user clarifying questions. 1. **Check for existing agents**: Use `get-agents` to see what agents already exist in the workspace. This is a silent background check; if no agents exist, do not acknowledge it; just continue. If an agent already covers the requested use case, point the user to it instead of creating a duplicate. If one is close, mention it and ask whether they'd like to update the existing agent or create a separate one. You can only update or delete an agent you created. `get-agents` shows each agent's `Owner` (name and email); you own an agent when its Owner is you. Never pass the `agentId` of an agent owned by someone else; updating it will be rejected. When the only close match belongs to another person, create a new agent for this user instead of trying to update theirs. 2. **Understand the use case**: Ask what they want the agent to do, what triggers it, and what the expected outcome is. Dig into vague requirements, e.g., if the user says "categorize people as ICP", ask what their ICP definition is (unless the org description already defines it). If they say "update fields after meetings", ask which fields. 3. **Narrow the scope, or batch on a schedule**: When a trigger would fire on every record of a type (e.g., all person creates, all deal updates), confirm the user actually wants that broad scope. Each agent run uses resources, so reducing unnecessary runs matters. Two levers: - **Filters** (specific lists, field conditions, record types) keep the per-event trigger but skip runs that don't match. - **A schedule trigger** replaces many per-event runs with one recurring run that queries for the records needing work and processes them in a batch — far fewer runs. Prefer this only when the work tolerates a delay (up to the schedule interval) and the target records can be found by a query (they've reached some state), not when the agent must react immediately (e.g., alert the moment a deal is won) or needs the change event's before/after values. 4. **Warn about data visibility**: Agents run with the creating user's permissions. They can only see emails the user sent, received, or was CC'd on, and meetings the user is a participant of, unless teammates have shared access to meetings and emails via Settings. Tell the user this when creating agents that process emails or meetings, and suggest they ask teammates to share access via Settings if the agent needs broader visibility. 5. **Suggest complementary agents**: If the agent they want would benefit from a prerequisite agent (e.g., they want post-meeting CRM updates but don't have an agent that classifies meeting types first), mention that and offer to create both. 6. **Consider delivery channel**: If the agent produces output that the user needs to see (e.g., pipeline reviews, daily summaries, alerts when deals change stage), ask how they want it delivered. The only supported delivery channels are: - **Slack** (via Slack MCP connector): post to a channel or DM. Most common for scheduled reports and alerts. - **Email**: send a summary email to the user or a distribution list. Do not suggest delivery channels that don't exist (e.g., posting in chat, push notifications, in-app alerts). Only ask about delivery when the agent produces user-facing output, not for agents that silently update CRM fields. 7. **Select tools and connectors**: Based on the agent's purpose, set `tools` and `mcp_servers` to explicitly list every tool the agent needs. Only listed tools are available; omitted tools cannot be used. For each tool, set its permission: - `always_allow`: the agent can use this tool without asking - `needs_approval`: the agent must ask the user before using this tool Set read-only tools (e.g., `query-data`, `get-records`) to `always_allow` by default. **Current state vs. history**: `query-data` reads the live CRM (PostgreSQL): current field values, open deals, this week's pipeline. It cannot see how a record changed over time. For any question about change history or point-in-time state (stage transitions, deals that moved to a later stage this week, time-in-stage, records created or updated per day, who changed a field and when) grant `query-analytics`, which queries the analytics event log of every CRM change (including historical stage transitions). Never have an agent approximate history from `_updated_at` or claim stage transitions aren't stored; they are recorded and queryable via `query-analytics`. For write tools (e.g., `create-or-update-records`, `send-email`), always ask the user whether they want the agent to use them freely or require approval each time. Present it concisely: "Should the agent update records automatically, or ask you first?" If the agent needs an MCP connector (e.g., Slack for posting messages, Linear for issue tracking), add it to `mcp_servers` and list the specific tools needed with their permissions. Server IDs come from existing agent configurations (via `get-agents`); calling with an unknown server ID returns an error listing the workspace's available MCP servers and their IDs. **Connect connectors before saving**: an agent can only use an MCP connector the user has actually connected. Before calling this tool with any `mcp_servers`, first check their status with `get-mcp-servers`. For any required connector that is not connected, call `connect-mcp-server` and wait for the user to finish connecting it (re-check with `get-mcp-servers`) before saving the agent. Never save the agent while a required connector is still unconnected; saving will fail validation, and the user should connect everything first. If the user must connect multiple connectors, get them all connected before the single create/update call. **Replacement semantics**: both `tools` and `mcp_servers` are full replacements, not merges. When updating an agent, always include the complete set of tools and servers the agent needs, not just the ones being added. Omitting a previously configured tool removes it. To keep existing tools unchanged, omit the `tools` / `mcp_servers` field entirely. When adding a tool to an existing agent, first use `get-agents` to read the current configuration, then pass the full set including the new addition. Whenever you change an agent's tools, review its instructions in the same update and revise any step that no longer matches the available tools, so instructions and tools never drift apart. **Tool dependencies**: some tools require other tools to function. If you include any tool on the left, you must also include the tool(s) on the right: - `query-data` → `get-schema` (the agent needs to load CRM schema before writing SQL) - `query-analytics` → `get-schema` (the agent needs CRM field names to read them out of the event log) - `create-or-update-records` → `get-schema` (the agent needs to discover writable field names) - `create-or-update-list` → `get-schema` (lists are defined by SQL queries that need schema knowledge) - `import-leads` → `find-leads` (importing requires search context from a find-leads search) **Write instructions in plain language**: describe what the agent should do ("look up the person record", "update the company", "post to the channel"), never the literal tool name or MCP tool ID. Tool names can change, and naming them in the instructions wastes a tool-search step and can confuse the agent. The `tools` and `mcp_servers` fields decide what the agent can use; the instructions only describe the goal. 8. **Choose a model**: Set `model` from the task's complexity yourself. Use `fast` for simple, narrow, deterministic work (classification, field extraction, tagging/routing, short summaries) and high-volume triggers — it is faster and meaningfully cheaper. Use `smart` (the default) for multi-step reasoning, judgment, or quality-sensitive writing like emails and summaries. Only ask the user to pick when the task's complexity is genuinely ambiguous. Skip this planning step when the user provides a fully detailed specification upfront (trigger, instructions, and expected behavior). When updating an existing agent, skip planning unless the request is vague and you need more context to make the right change. ## Backfill existing records Users often want an agent to process existing records, not just future ones. When they mention "backfill", "run on existing data", or "process all current records": Do not suggest creating a separate backfill agent. Instead, add backfill capability to the same agent by including an hourly schedule trigger alongside the event-based triggers. The agent's instructions should include a backfill section that: 1. Queries for unprocessed records in batches each run. 2. Tracks progress by filtering for records that still need processing. 3. When all records are processed, the agent edits its own instructions and triggers to remove the backfill logic and the schedule trigger, keeping only the event-based triggers for ongoing processing. 4. Notifies the user via Slack that backfill is complete. ## Popular agent ideas When the user is exploring what agents can do or has a vague request, suggest ideas from this list if they are relevant to the user's business context. These are just starting points; only suggest ones that make sense for the user's situation: - **Post-meeting CRM update**: After a meeting transcript is ready, extract key takeaways, update deal stage, next steps, and relevant fields on the associated records. - **Meeting type classification**: When a meeting is created, classify it (e.g., discovery, demo, negotiation, check-in) based on attendees, title, and context, then set the meeting type field. - **Post-email CRM update**: After an important email is received or sent, update relevant deal or contact fields (e.g., sentiment, next action). - **Weekly pipeline review** (Slack): Summarize pipeline changes, stale deals, and upcoming closes, then post to a Slack channel. - **Deal stage change alert** (Slack): When a deal moves to a key stage (e.g., closed-won, closed-lost), post a summary to Slack. ## After creating or updating an agent Once the agent is fully configured and ready to use, suggest a test run to the user. Do this after both creating and updating an agent. If you are still configuring it across multiple steps, wait until it is complete before suggesting a run. When you tell the user the agent is ready, also tell them which model tier it runs on (`fast` or `smart`) and why you chose it, so the model choice is never silent. On an update, mention the tier only when you changed it. When you have just created a new agent, also give the user a brief heads-up that running an agent consumes variable credits with a 1-credit minimum, and link the pricing docs: https://docs.clarify.ai/en/articles/15193255-agents#h_bbf4c7aa36. For an existing agent that has run at least once, use `get-agents` to inspect its stats and use Avg Credits/Run as its typical per-run cost. If an agent has no run history, say there is no cost history yet and do not estimate or provide a cost range. ## When the user reports an agent issue If the user says an agent isn't working or asks why it did something unexpected, do not immediately change the agent's instructions. First, consider: 1. Check whether the agent's current instructions already address the issue. If they don't, you can update them directly. 2. If the instructions look correct, use `get-agent-runs` to fetch the most recent run transcript and diagnose what actually happened. 3. After diagnosing, explain your findings and suggest targeted fixes. Then offer to rerun. When the reported problem is a wrong or broken record URL, do not repair or guess a corrected URL from the existing instructions; that text is not a source of truth for URLs. Take the correct URL from tool output, such as the `Link:` in the run transcript (via `get-agent-runs`), and copy it exactly, or rewrite the instructions to have the agent use the `Link:` its own tools return.

create-or-update-agent

Create a new artifact or write a new version to an existing artifact. An artifact is a named document with versioned content (e.g. a report, a plan, a draft) that the user can view and revisit over time. ## When to use this tool Pick the surface that fits the ask: - Answer inline in the chat reply for a single fact, number, or short answer. Do NOT create an artifact for a quick factual lookup. A qualifier like "quick" or "simple" on a report or dashboard ask describes the effort, not the format, so that ask still gets an artifact. - Create an artifact whenever the user wants a durable, revisitable deliverable: a report, dashboard, deck, analysis, breakdown, summary, overview, or plan, even when they never say the word "artifact". Reach for one especially for a multi-part deliverable, or for current-state / snapshot data. Artifacts open at their own URL and the user revisits them, so produce one instead of dumping the whole thing into the chat transcript. A deck, slides, a QBR, a pitch, or a readout is a slide deck built with `@clarify/ui/deck` (see "Building a deck"). - If the deliverable is really just a browsable set of records of a single object type (columns are direct fields, no aggregation or charts), a Clarify list via `create-or-update-list` fits better than an artifact. When the user asked for a report or analysis but a list would serve them, offer the list and explain the distinction first; if they explicitly asked for a list, just build it. ## Referring to it in chat When you mention the result to the user, name it by what it is — a dashboard, report, deck, sales document, or plan. Do not call it an "artifact" unless the user used that word first. ## Requirements and prerequisites Complete all four steps before you call this tool with new SQL. Every step is required. 1. Read the "artifact-docs" context with `read-context`, and complete every step it requires. It names any further context to read, because which ones exist depends on the workspace. 2. Run every query before you put it in `content`. Prove the independent ones together — emit them as one batch of parallel tool calls in a single turn, not one query per turn. Only a query that needs an earlier query's result stays serial. 3. State every definition you have not saved, and ask the user whether to save it. If the user does not answer, offer again in each reply until the user answers. 4. Call `get-artifact-component-doc` once. Pass every `@clarify/ui/*` component this version uses in one `specifiers` list. Call it every time, even for a component you used before in this conversation, or one you already know. Docs can change between calls, within one conversation or overnight. Do not trust memory from earlier in this conversation for current props. The one-line summaries below help you pick a component. They do not give its props. Never guess a stage name, a date field, or a metric definition. Never put a query in an artifact that you have not run. Never use a component's props from memory or from its one-line summary. Always call `get-artifact-component-doc` first. No exceptions. ## How it works Omit `artifact_id` to create a new artifact (`name` is required in this case). Pass an existing `artifact_id` to write a new version onto that artifact instead. Supply the new version in one of two ways — pass `content` or `edits`, never both: - `content`: the full TSX source. Use it to create an artifact, or to fully replace an existing version. - `edits` — a list of targeted `{ old_string, new_string }` replacements applied to the currently-saved source on the server. Prefer this to update an existing artifact, especially a large one: you send only the changed regions, so the update is smaller and faster and never has to re-emit the whole file. Read the saved source first with `get-artifact-source` and copy each `old_string` exactly, whitespace included; each must match once, or set `replace_all` to replace every occurrence. When updating an artifact you did not just author in this conversation, first read its current source with `get-artifact-source` so you patch what is actually saved. Some saved artifacts predate this guidance and carry no types. That is fine; unless the user asks you to rebuild it, patch it with `edits` and do not rewrite it just to add types. Before you save an artifact version, check the source you are about to send. Fix every clear defect in that same version without asking. This holds for source the user pasted too, unless they said to keep it exactly as given. Leave working code alone. Add no feature the user did not ask for. In this check, a missing date picker, header, or period comparison is not a defect. The authoring rules still apply to source you write yourself. Tell the user in one plain sentence what you fixed, with no build details, e.g. "I also fixed two queries and removed unused code." The "Self-check" in the "artifact-docs" context lists the defects: dead code, broken math, manual work a built-in covers, missing contract, slow queries. Read it with `read-context` if you have not in this conversation. Set `type` to "Dashboard" when the content you authored is an interactive dashboard, "Deck" when it is a slide deck, and "Document" when it is a page to read; leave it unset for other kinds of library item. ## Authoring the content (TSX) `content` is the TypeScript/TSX source for ONE React component, not an HTML document. Clarify compiles it (Babel strips the types, automatic JSX runtime) and mounts it in a sandboxed iframe; the scaffold owns the HTML shell, the theme, React/ReactDOM, and the mount call. Your source must: - Export a component named `ArtifactContents` (a default export also works). - Pad the root so the report never sits flush to the frame: give the top-level element `ArtifactContents` returns an outer padding class (`p-6`). Never return an unpadded root. Drop the padding only on a section you deliberately want edge-to-edge (a hero image, a full-width map). A slide deck does NOT get this padding: build it with `@clarify/ui/deck` (see "Building a deck"), which fills the frame with `h-screen`. - Import what it uses from the provided modules: `react` (v19.2.8) (hooks), `recharts` (v3.8.1) (charts ONLY), `framer-motion` (v12.40.0) (animation — import `m`, not `motion`; the scaffold already wraps the mount in `LazyMotion`), and the Clarify design-system components below (`@clarify/ui/*`: chrome, layout, controls). TSX is supported, so do not add a build step or import anything else. - Type it: give any local component you define a named props `type`, use `import type` for type-only imports, and never use `any` or a type assertion. - Prefer the design-system components for structure and text (cards, buttons, the `@clarify/ui/text` typography set); reach for bespoke components and/or standard HTML elements only for what they don't cover. - Render ALL text through the `@clarify/ui/text` components (`Heading1` to `Heading4`, `Text`, `CaptionText`), not raw `<p>`/`<span>`/`<h*>` and not type utilities (`text-lg`, `font-semibold`), so type stays on the design scale. - Write a `Text` nested inside another `Text` as `<Text as="span" size="inherit" weight="font-medium">` so it stays inline at the parent's size; a nested `Text` without `as` renders a `div` and breaks the sentence. Every URL, email address, and phone number is a `LinkText` with an `href` (`mailto:` for an email, `tel:` for a phone number), e.g. `Email <LinkText size="inherit" href="mailto:phil@acme.org">phil@acme.org</LinkText> for access.` A bare or bold email, URL, or phone number is a bug: the viewer cannot click it. - Use only standard Tailwind utilities. The theme ships the standard layout, spacing, and sizing utilities plus the semantic color utilities in Styling below. Avoid arbitrary-value classes (`p-[37px]`), because only standard utilities are guaranteed to be emitted. Chart colors come from `useArtifactTheme()` instead (see Charts below). - Emoji are allowed, but prefer a Clarify icon (`@clarify/ui/icon`) whenever one fits. Never mix the two in one context: a single list, row of cards, or slide uses icons throughout or emoji throughout, never two emoji and one icon. - NOT emit `<!doctype>`, `<html>`, `<head>`, `<body>`, a root/mount node, a `<script>` tag, or any `createRoot(...)` call — the scaffold provides all of that, and emitting them breaks the artifact. ### Styling Color comes only from these semantic utilities. Each one follows dark mode and the workspace palette, so one class renders right in both modes: - `text-fg-1`, `text-fg-2`, `text-fg-3`, `text-fg-4`, `text-fg-onbrand`, `text-fg-on-inverse` - `bg-canvas`, `bg-surface`, `bg-subtle`, `bg-muted`, `bg-hover`, `bg-selected`, `bg-inverse` - `border-border`, `border-border-subtle`, `border-border-strong` - `text-danger`, `text-warning`, `text-success`, `text-info`, `bg-danger`, `bg-warning`, `bg-success`, `bg-info`, `border-danger`, `border-warning`, `border-success`, `border-info` - `bg-danger/10`, `bg-warning/10`, `bg-success/10`, `bg-info/10` - `bg-brand-subtle`, `text-brand-subtle-fg` - `text-accent-1`, `text-accent-2`, `text-accent-3`, `text-accent-4`, `text-accent-5`, `text-accent-6`, `bg-accent-1`, `bg-accent-2`, `bg-accent-3`, `bg-accent-4`, `bg-accent-5`, `bg-accent-6`, `border-accent-1`, `border-accent-2`, `border-accent-3`, `border-accent-4`, `border-accent-5`, `border-accent-6`, `from-accent-1`, `from-accent-2`, `from-accent-3`, `from-accent-4`, `from-accent-5`, `from-accent-6`, `via-accent-1`, `via-accent-2`, `via-accent-3`, `via-accent-4`, `via-accent-5`, `via-accent-6`, `to-accent-1`, `to-accent-2`, `to-accent-3`, `to-accent-4`, `to-accent-5`, `to-accent-6` - `bg-accent-1/10`, `bg-accent-2/10`, `bg-accent-3/10`, `bg-accent-4/10`, `bg-accent-5/10`, `bg-accent-6/10` - `text-ai-1`, `text-ai-2`, `text-ai-3`, `from-ai-1`, `from-ai-2`, `from-ai-3`, `via-ai-1`, `via-ai-2`, `via-ai-3`, `to-ai-1`, `to-ai-2`, `to-ai-3` - `from-ai-1/10`, `from-ai-2/10`, `from-ai-3/10`, `via-ai-1/10`, `via-ai-2/10`, `via-ai-3/10`, `to-ai-1/10`, `to-ai-2/10`, `to-ai-3/10` - Set a background only through a surface token (`bg-canvas`, `bg-surface`, `bg-subtle`, `bg-muted`, `bg-inverse`) or a tint (`bg-brand-subtle`, `bg-accent-1/10`, `bg-danger/10`). Use `@clarify/ui/card` for a raised surface before you reach for `bg-surface`. On `bg-inverse`, color text with `text-fg-on-inverse`, which flips with the surface. `text-fg-onbrand` is a fixed white for an accent fill, so it vanishes on the dark-mode inverse. - Never use a palette shade (`text-gray-600`, `bg-blue-50`) or a hex value, and never a CSS variable in an inline style for color. A shade ignores dark mode and the workspace palette. When the user asks for a specific color, use the nearest accent or status utility. - Never restyle the internals of a design-system component, such as a Block's border or a Card's padding. Wrap the component or pick a different one. - Give each surface one accent moment at most: one `text-accent-1` figure, one highlighted series, or one call to action. - Keep a gradient rare. Build it from accent stops only (`bg-gradient-to-br from-accent-1 to-accent-3`) and count it as the surface's one accent moment. ## Clarify design-system components These `@clarify/ui/*` modules are available in the frame and render with the workspace theme (light/dark) automatically. Import only what you use. See "Requirements and prerequisites" above for when to call `get-artifact-component-doc` for a component's exact props. - `@clarify/ui/button` — A themed button. Use for actions inside an artifact (filters, toggles). Standard button attributes (onClick, disabled, type) work as usual. To link somewhere, use a real `<a href>` (or RecordLink for a record), not a button. - `@clarify/ui/card` — A themed surface for grouping content into panels: the default frame for a section, chart, or stat. Compose the parts; CardTitle renders a heading, CardDescription muted subtext. Defaults: variant "default" (shadowed), radius "default". - `@clarify/ui/text` — The themed typography set. Use these for ALL text instead of raw <p>/<span>/<h*> or Tailwind text utilities, so weight, size, and color stay on the design scale. DisplayText and Heading1 to Heading4 are headings (largest to smallest); CaptionText is small muted; LinkText is an anchor. Write a Text nested inside another Text as <Text as="span" size="inherit" weight="font-medium"> so it stays inline; a nested Text without as renders a div and breaks the sentence. A nested LinkText takes size="inherit". Every URL, email address, and phone number is a LinkText with an href (mailto: for an email, tel: for a phone number). A bare or bold email, URL, or phone number is a bug: the viewer cannot click it. - `@clarify/ui/avatar` — A circular avatar for a person or company. Compose AvatarImage with an AvatarFallback (initials shown while the image loads or is missing). Set size via className (e.g. size-8). - `@clarify/ui/badge` — A small status/label pill — deal stage, a count, a state. - `@clarify/ui/icon` — Clarify's icon set, imported by name as `<Name>ClarifyIcon`. Reach for one wherever a label earns a glyph: a section heading, a status row, a list bullet, a stat caption. Clarify's own nouns have their own icons, so prefer the specific name over a generic one: an autonomous agent is `AgentClarifyIcon`, not `PeopleClarifyIcon`. `ClarifyAIClarifyIcon` and `RepFaceClarifyIcon` draw Rep's face: use them only for Rep itself, never as the Clarify logo or a company logo. For the workspace's own logo use `BrandLogo` (from `@clarify/ui/brand-logo`). Draw no other company's logo, Clarify's included. Every icon paints with `currentColor`, so color comes from a `text-*` utility on the icon or its parent (`text-success`, `text-warning`, `text-danger`, `text-fg-3`, `text-accent-1`) and size from the `size` prop, 16 by default. Emoji are still fine, but prefer an icon when one fits, and never mix icons and emoji in the same list, card row, or slide. The full set, each used as `<Name>ClarifyIcon`: Activity, AddAbove, AddBelow, Agent, Agent2, AIEmail, AINote, AIPlay, AITask, Alarm, AlignLeft, AlignRight, AngelList, ArrowDown, ArrowDownLeft, ArrowDownRight, ArrowLeft, ArrowLeftRight, ArrowRight, ArrowTrendDown, ArrowTrendUp, ArrowUp, ArrowUpDown, ArrowUpLeft, ArrowUpRight, Artifact, ArtifactDashboardSparkle, ArtifactDeckSparkle, ArtifactDocumentSparkle, Attach, BankNote, Bell, BellCheck, BellOff, BillingPlans, Binoculars, BoardView, Bolt, Book, Bookmark, Box, Braces, Briefcase, Calendar, CalendarCross, Campaign, Car, CaretDown, CaretLeft, CaretRight, CaretUp, Changelog, ChatDocked, ChatFloating, Check, Checkbox, CheckCircle, CheckCircleFilled, ChevronDown, ChevronLeft, ChevronRight, ChevronsUpDown, ChevronUp, ChromeExtension, Circle, CircleDashed, CircleFilled, ClarifyAI, Cleanup, Clock, Collapse, Columns, Comment, Company, Component, Connected, Connectors, CreditCard, Credits, CursorClick, Customize, Database, DateNumbers, Deal, Delete, Deny, DesktopApp, DocumentUpload, Dot, Download, DragHandles, Duplicate, DynamicClock, Edit, EditOff, Email, EmailForward, EmailReply, EmailReplyAll, Enter, EnumFilled, EnumOutline, ErrorCircle, Expand, Eye, EyeClosed, Facebook, FileText, Filter, Flag, FlaskConical, Folder, Globe, GraduationCap, Granola, Graph, GroupView, Hand, Handshake, Hash, Heart, Home, Image, IMessage, ImportToList, Inbox, InfoCircle, Instagram, Integrations, Intercom, InviteMembers, Json, Key, Keyboard, LastRun, Layers, Link, LinkedIn, ListView, Location, Lock, Logout, MapPin, Megaphone, Members, Mention, Menu, Minus, Mobile, Monitor, More, MultiSelect, NewChat, Note, NoteBook, Number, Objects, Package, Pause, People, Phone, Pin, Plus, Popout, PriorityHigh, PriorityLow, PriorityMedium, PriorityUrgent, Puzzle, Question, QuestionCircle, Receipt, Record, Refresh, RepFace, Rocket, RTEBold, RTECode, RTEH1, RTEH2, RTEH3, RTEItalic, RTElistCheck, RTElistOrdered, RTElistUnordered, RTEParagraph, RTEQuote, RTESmiley, RTEStrikethrough, RTEUnderline, Search, SendEmail, Settings, SettingsAlt, Shield, ShoppingCart, SidebarLeft, SidebarLeftOpen, SidebarRight, SidebarRightOpen, Signal, Skill, Slack, SocialAngellist, SocialFacebook, SocialInstagram, SocialLinkedIn, SocialX, Sort, SortAsc, SortDes, Sparkle, Spinner, Stage, StageOfDeal, StarFilled, StarOutline, StatusBlocked, StatusCanceled, StatusDone, StatusFailed, StatusInProgress, StatusPaused, StatusScheduled, StatusTodo, Stop, Store, Summary, Tag, TagRemove, Target, Text, ThumbsDown, ThumbsUp, Ticket, ToggleLeft, ToggleRight, Trophy, Truck, Typography, Undo, Unread, Upload, Users, Variable, VerificationFail, VerificationSuccess, Video, VideoBack10s, VideoCC, VideoForward10s, VideoFullScreen, VideoOff, VideoPause, VideoPIPExpand, VideoPIPMinimize, VideoPlay, VideoPlayFilled, VideoVolumeFull, VideoVolumeMute, View, Warning, Webhook, Workflow, Wrench, X, XSocial, Zap. - `@clarify/ui/switch-icon` — The default way to show a boolean in a report: a static on/off status icon (green when on, gray when off) for an active flag, an enabled setting, a yes/no cell. It shows state driven by `checked`; it is not an interactive control. Reach for `@clarify/ui/switch` only when the user must flip the value. - `@clarify/ui/switch` — An interactive on/off toggle (Radix). Use it only when the report needs a real control the user flips to change what they see; drive it with `checked` + `onCheckedChange` and your own state. To show a boolean as read-only status, use `@clarify/ui/switch-icon` instead. - `@clarify/ui/tabs` — A sectioned content switcher. Each TabsTrigger and its TabsContent share a `value`; drive it with defaultValue (uncontrolled) or value + onValueChange. - `@clarify/ui/clarify-avatar` — Clarify's branded avatar: shows the image, else colored initials, shaped by the object type (round for people, squared for companies/deals). - `@clarify/ui/name-chip` — A compact name + avatar chip for a person or company (a deal owner, a contact). Falls back to colored initials when there is no image. - `@clarify/ui/dashboard-header` — The header at the top of a dashboard — title and an optional scope line (period, owner, filters applied). The "Last updated" freshness label and the refresh-all button are added automatically from the dashboard's own queries; do not pass them. Use exactly one per dashboard; for a section title inside the report use BlockHeader instead. - `@clarify/ui/filter-bar` — A row that lays out filter and selector controls under the header, for reports meant to be re-sliced by the viewer. Skip it on a fixed view; it is only layout — put the controls inside it. - `@clarify/ui/date-range-picker` — A dashboard's time control, placed in the FilterBar. Only add it when the artifact has ClickHouse (event) queries the range can scope — timeRange applies to ClickHouse only, so a Postgres-only (current-state) artifact must not include one; it would scope nothing. It opens on the last 30 days by default, so keep that default unless the report needs another window. To change it, defaultQuickSelect must be one of the built-in presets exactly — "Today", "Yesterday", "Last 7 days", "Last 30 days", "Last 90 days", "Month to date", "Year to date", or a quarter label like "Q3 2026" — an unrecognized label (e.g. "Last 6 months") is ignored and falls back to the 30-day default; for any other span pass defaultDateRange instead. Hold its onApply({ from, to }) range in state and pass it to each ClickHouse section as useQuery(sql, { timeRange: range }) — the backend scopes the query to it, so the picker label always matches what the queries run. Its Clear button sets the picker to "all time": onApply then fires with from/to undefined, so useQuery runs over all data — never pass a partial range. onApply also gives `previous` (the equal-length window just before the range, present only for a preset) for period-over-period comparison. Dates after today are disabled by default; set canSelectFutureDates only for a forward-looking report (pipeline or forecast scoped by a future close date). Never fetch all rows and slice client-side, and never interpolate the dates into your SQL. - `@clarify/ui/filter` — A dropdown filter for the FilterBar — lets the viewer narrow the dashboard by a value (owner, stage, region). Single-select by default (value is a string, onChange fires undefined when cleared); pass multiple for multi-select (value is a string[]). Hold the selection in state and pass it to each section's useQuery so the backend scopes the query; never fetch all rows and slice client-side. - `@clarify/ui/block` — The card every metric, chart, or table sits in — never render one bare. Give it the section title with `title` (plus optional `info` for a definition and `description`), and pass the section's `query` (a useQuery result). The Block renders that query's loading skeleton, error, empty, and refresh states, then reveals your content once the rows arrive — so never hand-write isLoading/error/empty branches. Build the content from `query.rows`. Every query-driven block MUST also pass `underlyingQuery={{ sql, source?, title?, columns }}` — the detail records behind the aggregate — so the block offers a "See underlying data" drilldown (a block with a `query` but no `underlyingQuery` is incomplete). Author the detail SQL as the individual records (no GROUP BY), match its `source` to the block's query, and author `columns` with the right headers, formats (currency/percent/count/date), alignment, and any `render` — leave `columns` out only when you can't determine them, and the table falls back to auto-deriving number/date/text from the query's column types. Make every row's name link to its record by projecting `entity_id` and `entity_type` next to the record's name (aliased `name`) — on Postgres `deal._id AS entity_id, 'deal' AS entity_type, deal.name AS name` (use the record's own entity in place of `deal`); on ClickHouse `entity_id`, `entity_type`, and `argMax(JSONExtractString(properties,'name'), timestamp) AS name`. The framework reads `name`, `entity_id`, and `entity_type` literally off each row, so any other alias (`deal_id`, `record_id`, a bare `id`) silently renders plain text — no link, no error, and nothing to self-heal from. Get the three names right the first time. Keep a `name` column in `columns` — it renders the record as a clickable link — but leave `entity_id` and `entity_type` out of `columns`; they only carry the link target and never render. - `@clarify/ui/block-header` — A block's header — a title, an optional description, an optional info tooltip for a definition, and an action row. Prefer passing `title`/`info`/`description` straight to `Block` (it renders this header for you); reach for BlockHeader directly only for a header outside a Block. Keep it to title, description, and one info affordance. - `@clarify/ui/section-divider` — A light separator, optionally labeled, between clusters of blocks in a long artifact. Prefer whitespace first; reach for this only when a section break needs to be explicit. - `@clarify/ui/use-query` — The only way to fetch live workspace data — a React hook with loading, refreshing, and error state, a refresh action, and auto-refetch when the SQL or timeRange changes. Give each data section its own useQuery so one slow or failed query never blanks the others. Pass a time window as useQuery(sql, { timeRange }) to scope the query server-side; never interpolate dates into the SQL. Give every query a title — the same string you pass to that Block — surfaced in server logs so a failing query is identifiable without decoding its SQL. Show a period-over-period comparison by default on time-scoped sections: add compareToPrevious — pass `range.previous ?? true` (`true` runs the same SQL for the equal-length window right before timeRange; the DateRangePicker onApply payload's `previous` is calendar-precise) — and read the prior period from `previousRows` (same shape as `rows`). It is a no-op without a timeRange. - `@clarify/ui/artifact-theme` — The theme for charts. Call useArtifactTheme() and spread its `charts` values onto stock Recharts props so colors, axis, legend, and tooltip match the report and re-theme with light/dark. Never hardcode chart colors. Color each `<XAxis>`/`<YAxis>` with `stroke={charts.axis.line}`, else Recharts draws its `#666` default. Pick the color group by the decision tree (stop at first match): positive/negative state → `charts.positive`/`charts.negative`/`charts.neutral`; ordinal dimension (stage, priority, tier, size/amount band) → `charts.sequential[i]` light-to-dark ordered by the band sequence (not the measure), even for a single series; more than one series in one space → `charts.categorical[i]` (six colors, wrap past six with `categorical[i % 6]`; `charts.other` for null/unknown only); otherwise a single `charts.primary`. Give pie/donut slices a thin `charts.pieStroke` border (half-opacity, blends light/dark). The legend key is a circle in our font (charts.legend). Order the query rows by the dimension: rank by the measure descending, else the dimension's own order (stage, priority), alphabetical only as a last resort. Recharts `<Legend>` re-sorts keys alphabetically unless you pass `itemSorter={null}`, so ALWAYS set `itemSorter={null}` on `<Legend>` to keep it in the row order and matching the tooltip. Size the chart on the chart itself with `responsive width="100%" height={320}`. A fixed pixel height is required and a parent div's height does not flow into the chart. Give the Y axis headroom so the tallest value never touches the top. On bar/line/area set `domain={[0, (max) => Math.ceil(max * 1.1)]}` on the `<YAxis>`. - `@clarify/ui/value-text` — Formats a single value for display — number, currency, percent, count, duration, or date. Reach for it for every numeric or date value so formatting stays consistent; it inherits the surrounding text size and color. Percent takes a fraction (0.12 → 12%); duration takes milliseconds; set `compact` to abbreviate large numbers ($2,480,000 → "$2.48M"). - `@clarify/ui/trend-indicator` — A change indicator: a direction arrow, the change value, and a comparison label. You rarely build this by hand — on a KPI, add a `comparison` to `MetricBlock` (`comparison={{ field, label }}`) and it renders this for you from the query. The comparison is free: `useQuery(sql, { compareToPrevious })` re-runs the SAME query for the prior period, so you never write a second query or diff values yourself — no reason to skip a trend on a time-scoped tile. Construct `TrendIndicator` directly only for a bespoke comparison whose two sides you already hold. `direction` sets the arrow; `sentiment` sets the color and defaults from direction — set `sentiment` to invert when up is bad (churn, cost). - `@clarify/ui/metric-block` — A single KPI tile: a small title (with an optional definition tooltip), a large value, and under it an optional period-over-period trend and/or a muted caption. Self-contained (its own card), so drop it straight into a KPI strip, never wrap it in a Block. Group them in a 3-across grid and wrap to more rows as the count grows. Set `compact` to abbreviate large headline numbers ($2.48M, 47K). Give each tile its OWN `query` (a useQuery result) whose SQL returns exactly one row and the single value shown, and read it as `query.rows[0]?.<col>`. Do the aggregation in SQL (count/sum/avg/…, or a ratio via `countIf(…) / count()`) so a zero result shows as the value (0) rather than an empty state. Never pass a multi-row query and derive the value in JS (`rows.reduce(…)`, summing or dividing across rows, or plucking one row out of many). Show a period-over-period trend by default whenever the tile is time-scoped: run the query with compareToPrevious and pass `comparison={{ field: "<col>", label: "vs previous period" }}`. `field` names the same column `value` reads, and the tile pulls the prior value and window straight from the query and computes the change itself (never compute a delta in code). Add `isInverted: true` for up-is-bad metrics (churn, cost). It shows a % for a nonzero prior, the raw figure for a prior of 0 (0 → 10 reads "+10"), or "Same as …" when unchanged; a missing/non-numeric prior or value shows no trend. `description` is a separate muted caption. Whenever the tile has a `query`, it MUST also pass `underlyingQuery={{ sql, source?, title?, columns }}`, the detail records behind the metric, so the tile offers a "See underlying data" drilldown (a query-backed tile with no `underlyingQuery` is incomplete); author it as the individual records (no GROUP BY) and give `underlyingQuery.columns` the right headers and formats, leaving them out only when the right columns are unknown. Make every row's name link to its record by projecting `entity_id` and `entity_type` next to the record's name (aliased `name`). On Postgres `deal._id AS entity_id, 'deal' AS entity_type, deal.name AS name` (use the record's own entity in place of `deal`); on ClickHouse `entity_id`, `entity_type`, and `argMax(JSONExtractString(properties,'name'), timestamp) AS name`. The framework reads `name`, `entity_id`, and `entity_type` literally off each row, so any other alias (`deal_id`, `record_id`, a bare `id`) silently renders plain text: no link, no error, and nothing to self-heal from. Get the three names right the first time. Keep a `name` column in `columns`, which renders the record as a clickable link, but leave `entity_id` and `entity_type` out of `columns`; they only carry the link target and never render. A static tile with no `query` skips it. `MetricValue` is the same value, trend, and caption with no card and no title, for a headline number on a slide inside `SlideData`: pass `size="headline"` there and let the slide carry the metric name. - `@clarify/ui/data-table` — A sortable table of rows — reach for it whenever a block shows tabular data. Presentational: it renders already-loaded rows, so wrap it in a Block that owns the loading / empty / error chrome and pass `rows={query.rows}` and `truncated={query.truncated}`. For columns, either pass `columnTypes={query.columns}` to auto-derive them (numbers right-align, dates format, headers show even on 0 rows) and omit `columns`; or pass explicit `columns` — `{ key, header?, format?, align?, render? }` — when you need currency/percent/count formatting or a custom cell (auto-derive only knows number/date). `key` reads and sorts the cell; `header` defaults to `key`; `format` is one of number | currency | percent | count | duration | date; `align="right"` suits numbers; `render: (row) => …` draws a badge/chip/link (sorting still follows `key`). For sticky total / subtotal rows, pass `footerRows` — an array of `{ cells: { [columnKey]: cell } }`, one entry per row, top-to-bottom; each cell is EITHER `{ aggregate: "sum" | "avg" | "min" | "max" | "count" }` (computed over the shown rows and formatted with that column's format; `count` renders as an integer; on a date column only `count` applies, the others are dropped) OR `{ content: <node> }` for a label ("Total") or a precomputed value. An aggregate totals only the shown rows, so a `sum` under-counts when `truncated`. Every row always renders; by default ~10 show before the table scrolls — usually omit `visibleRows` and set it only to change how many are visible before scrolling, never to the total row count (that caps nothing and falls back to the default ~10). Do aggregation and column selection in SQL — never trim wide rows in the component. A `name` column links to its record automatically when the rows carry `entity_id` and `entity_type` — the SAME contract as `underlyingQuery`, so project those two next to the name (`d._id AS entity_id, 'deal' AS entity_type` on Postgres; `entity_id` and `entity_type` on ClickHouse) in any table query you want linked, not just drilldowns. All three names are read literally, so a different alias (`deal_id`) silently renders plain text. Leave `entity_id`/`entity_type` out of `columns` — auto-derive hides them once a row links, and listing them explicitly renders raw ids as their own columns. A column `render` overrides the link. - `@clarify/ui/record-link` — A record's name as a clickable chip that opens its record page. A `DataTable` already links its `name` column on its own, so reach for this only outside that column: a second record column in the same table (via that column's `render`), or a non-table layout like a card grid or a list. `objectName` is the entity (`deal`, `company`, `person`), `recordId` its id; take both from the row's `entity_type` / `entity_id`. It degrades instead of breaking: no `recordId` renders a non-clickable chip, no `objectName` renders plain text. A plain `<a href>` navigates too: an in-app path opens in the same tab, an external URL in a new tab. But prefer RecordLink for a record's name so you get the chip styling and this safe degradation, rather than hand-building a record URL. - `@clarify/ui/brand-logo` — The workspace's own logo as an `<img>`. Size it by height with `className`, between `h-6` and `h-8` with `w-auto`: it may be a small square icon that blurs when larger. In dark mode it draws its own white plate, so add no background, padding, or rounding around it. The logo is often unset or fails to load, and then it renders nothing. So never tell the user you added a logo, and never build a layout around it: the layout must still look right with it absent. - `@clarify/ui/chart-tooltip` — The Recharts `<Tooltip>` wearing Clarify's tooltip frame (an inverted rounded card). It IS the Recharts Tooltip, so render it directly inside a Recharts chart (`<ChartTooltip />`) and never pass it to another element's `content` prop. Nesting one inside a Tooltip's `content` recurses without end. With no `content` it renders Clarify's legend body: per series a color dot, the neutral name, and the right-aligned value. `formatter` and `labelFormatter` still work. Pass your own `content` to override the body. - `@clarify/ui/deck` — A slide deck, for anything the user will present: a deck, slides, a QBR, a pitch, a readout. `Deck` owns navigation, the thumbnail rail, the overview grid, present mode, and the slide transition; each `Slide` is a bare 960×540 design-px canvas (scaled to fit, clipped, never scrolling) with only `children`, `notes`, and `className`, so the author composes the whole slide with the text components, the semantic color utilities, and flex, grid, or absolute positioning. The slide sets its own type scale, so the text components render at slide size: `CaptionText` 14px, `Text` 16px, `Heading2` 24px, `Heading1` 32px, `DisplayText` 44px, and `size="text-4xl"` 56px, `text-5xl` 72px, `text-6xl` 86px for a cover title or a headline number. `SlideData` takes the slide's `query` (and `underlyingQuery`, same contract as Block) and renders the loading, error, empty, and refresh states around a chart, a `DataTable`, or a `MetricValue` with `size="headline"`, with no card. `Steps` / `Step` reveal a slide one beat at a time. `useSlidePageNumber()` returns `{ current, total }`. Slides must be direct children of `Deck` (fragments are fine; a component that renders slides is not). The authoring rules (every `useQuery` hoisted above the `Deck`, one idea per slide, semantic colors only, `className="h-screen"`) are in the "Building a deck" section of the artifact tool. - `@clarify/ui/document` — A long-form page, for anything the user will read: a business case, a prospecting brief, a proposal, a memo, an account plan. `Document` owns the title block (`title`, `description`, `meta` badges), the page width and text scale, the paragraph measure and leading, and a table of contents that follows the reader and jumps to any section. Each `Section` has a `title` and children; a `Section` inside a `Section` is a subsection, and its heading level and table-of-contents depth come from the nesting. `Callout` (`tone`: note, info, warning, success, danger) is a tinted aside. Body copy is `Text as="p"`, a list is a plain `ul` or `ol` with `Text as="li"` items, and a side-by-side row is a grid, as the usage shows. A document about workspace data is live like a dashboard: every figure renders from `query.rows` through a `MetricBlock`, `MetricValue`, chart, or `DataTable` in a `Block` inside a `Section`, and prose interpolates figures from the rows. The authoring rules (every `useQuery` hoisted above the `Document`, every heading a `Section`, `className="h-screen"`) are in the "Building a document" section of the artifact tool. ## Fetching live data Render live workspace data with the `useQuery` hook (`@clarify/ui/use-query`) — the preferred way to fetch. It wraps the data path with loading, error, and refresh state, so a section needs no fetch boilerplate. The iframe has no network access, so never `fetch` or import from another origin. - `const query = useQuery(sql)` → `{ rows, columns, rowCount, truncated, isLoading, isRefreshing, error, refresh, source }`. Import it from `@clarify/ui/use-query`. Give EACH data section its own `useQuery` — never gate the whole artifact behind one spinner — so one slow or failed query never blanks the sections that are ready. - **Hand the query to a `Block`; do NOT hand-write loading/error/empty.** Wrap each section in `<Block title="…" query={query}>…</Block>` (or, for a KPI, `<MetricBlock … query={query} value={query.rows[0]?.x} />`). The Block owns that query's loading skeleton, error state, empty state, and refresh control, and reveals your content once the rows arrive. Never write your own `if (isLoading)` / `if (error)` / `if (!rows.length)` branch or a `LoadingOrError`-style helper, and never pass `isLoading ? null : value` — that duplicates the Block and drifts from the design system. Read `rows` straight off the query (`query.rows`) for the content you render inside. - **Do all aggregation, math, and filtering in SQL — never in JS.** The query returns exactly the rows and values you render; the component only reads `query.rows` and displays them. Never sum, divide, average, count, slice, or filter across rows in code (`rows.reduce(…)`, `rows.filter(…)`, `rows.slice(…)`). Push it into the SQL (`count()`, `sum(m_amount)`, `avg(…)`, a ratio via `countIf(…) / count()`, or a `WHERE` / `GROUP BY` / `ORDER BY` / `LIMIT`). A `MetricBlock` is the scalar case: its query returns exactly one row and the single value shown, read as `query.rows[0]?.<col>` (a scalar query also makes a zero result render as `0` rather than an empty state). Merging two query results by a stable key to add columns to one table (see "Keep queries simple") is a join by key, not this banned across-rows aggregation. - **Show a period-over-period trend by default.** "Is this up or down from before?" is the first question a reader asks of any KPI or trend, so a comparison is the highest-value thing most sections carry — add one to **every time-scoped `MetricBlock` and single-measure line chart** unless a prior period is genuinely not meaningful (see the skip list). This costs you nothing extra: do NOT write a second query and do NOT diff values in JS. Add `compareToPrevious={range.previous ?? true}` to the section's EXISTING `useQuery` (the DateRangePicker's calendar-precise prior window, else the equal-length shift) — the host re-runs that same SQL for the prior period and returns it as `previousRows` (same shape as `rows`). Never hesitate for lack of a comparison query; the flag *is* the comparison query. - On a `MetricBlock`, pass `comparison={{ field: "<col>", label: "vs previous period" }}` where `field` is the same column `value` reads; the tile pulls the prior value and window from the query and computes the change itself — never compute a delta in code. Add `isInverted: true` when up is bad (churn, cost). - On a line chart, plot the prior window as a second series (see "Comparing two periods on a chart" under Charts). - Skip it only where there is no meaningful prior period: a non-time snapshot (no `timeRange`), a Postgres current-state read, a pure breakdown or distribution (share by stage / owner / category), or a cumulative running-total measure. It is a no-op without a `timeRange`. - The result carries `{ columns, rows, rowCount, truncated }`. `columns` is `{ name, type }[]` (type is one of number | string | boolean | date | datetime), present even for a 0-row result — hand it to a `DataTable`'s `columnTypes` to auto-align/format and keep headers on an empty result. When `truncated` is true the row cap was hit — tell the user the data was limited. `error` is the typed failure (with a `code`); `refresh()` re-runs the query. - Choose the store per query with `useQuery(sql, { source })`. The default (omit it) is ClickHouse, the analytics event log — use it for history, trends, point-in-time, and stage transitions. Pass `{ source: 'postgres' }` only when the question is about current record state (the values as they are now, a plain SELECT), which the event log can't answer as directly. The SQL dialect differs per source (see the schema guidance below), so pick the source first, then write for it. - Pass a static SQL string literal so the query stays predictable and validatable — never build SQL from runtime values, including dates. To scope a query to a time window, pass the range to `useQuery` (below); the backend applies it — never interpolate `from`/`to` into the SQL. - To scope a section to a time window (e.g. a DateRangePicker's range), pass it as the second argument: `useQuery(sql, { timeRange: { from, to } })`. The backend applies it as a table-level row filter on `analytics.event`, so every read of that table — nested subqueries, CTEs, and each `UNION` branch — is filtered independently and the SQL stays static; never add your own `timestamp` bounds for the picker's window. `useQuery` re-runs on its own when the SQL or range changes, so the report re-slices on Apply with no extra wiring. `timeRange` applies to the ClickHouse source only — a Postgres query ignores it (see below for its dates). - **Scope every ClickHouse query to the artifact's window with `{ timeRange }`.** The default source is the event log, so a metric read over all history is almost never what the reader wants — pass `{ timeRange }` to every ClickHouse `useQuery`, and give the artifact a date control (a `@clarify/ui/date-range-picker`) to drive it. Add the picker **only when the artifact has ClickHouse queries**, and never for a named period. A Postgres-only artifact gets no picker: it is current record state, with date `WHERE` filters relative to today (`now()`, `CURRENT_DATE`, `date_trunc`). A named period of any tense ("July", "Q4") is never Postgres-only, since current state filtered to it empties once it ends. Read it from the event log with typed dates: a fixed `timeRange` for activity, and for state an `argMax` with `timestamp < '<day after end>'`, which tracks the period while it runs and freezes at its end. The picker defaults to the last 30 days, so queries stay fast; the viewer can Clear it to all time. With no picker, a rolling ask ("this month") builds its `timeRange` from `new Date()`. Ask when the user could mean either. State the window in the UI. - **Give every `useQuery` a `title` — the same string you pass to that section's `Block`.** So a section wrapped in `<Block title="Deals by stage">` fetches with `useQuery(sql, { title: 'Deals by stage' })`. The title is forwarded to the server logs so a failing query is identifiable without decoding its SQL; it has no effect on the result. - **A detail (drilldown) query must project `name`, `entity_id`, and `entity_type`.** A block's `underlyingQuery.sql` returns individual records, and the framework reads those three column names literally off each row to build the record link. On Postgres neither `entity_id` nor `entity_type` exists as a column, so alias them yourself — `d._id AS entity_id, 'deal' AS entity_type, d.name AS name`; on ClickHouse project `entity_id` and `entity_type`. When the name is a secure field (a meeting's title), also project `_has_access` on Postgres (`m._has_access AS _has_access`) so a withheld title shows "Title hidden" instead of a blank chip; ClickHouse redacts it in place. Any other alias (`d._id AS deal_id`) silently renders plain text with no link and no error, so there is no failure to self-heal from — get the three names right while you write the SQL. ### Minimal example ```tsx import { BarChart, Bar, XAxis, YAxis, CartesianGrid } from 'recharts'; import { useQuery } from '@clarify/ui/use-query'; import { useArtifactTheme } from '@clarify/ui/artifact-theme'; import { Block } from '@clarify/ui/block'; import { Heading2, CaptionText } from '@clarify/ui/text'; // A local component types its own props. type SummaryProps = { title: string; caption: string }; function Summary({ title, caption }: SummaryProps) { return ( <div className="mb-4"> <Heading2>{title}</Heading2> <CaptionText>{caption}</CaptionText> </div> ); } export function ArtifactContents() { const { charts } = useArtifactTheme(); const query = useQuery( "SELECT entity_type, count() AS events FROM analytics.event WHERE workspace_slug = '<your workspace>' GROUP BY entity_type ORDER BY events DESC", { title: 'Events by type' }, ); // No isLoading/error/empty branches. The Block renders those from `query` // and shows the chart once `query.rows` is ready. return ( <div className="p-6"> <Summary title="Event activity" caption="Events by record type, all time" /> <Block title="Events by type" query={query}> <BarChart responsive width="100%" height={320} data={query.rows}> <CartesianGrid stroke={charts.grid.stroke} vertical={false} /> <XAxis dataKey="entity_type" stroke={charts.axis.line} tick={{ fill: charts.axis.tick, fontSize: charts.axis.fontSize }} /> <YAxis domain={[0, (max) => Math.ceil(max * 1.1)]} stroke={charts.axis.line} tick={{ fill: charts.axis.tick, fontSize: charts.axis.fontSize }} /> <Bar dataKey="events" fill={charts.primary} /> </BarChart> </Block> </div> ); } ``` ## Charts Charts are Recharts (imported from `recharts`), styled by the artifact theme so every report's charts read as one system. Four rules: - **Size the chart with `responsive` + `width="100%"` + a fixed pixel `height`, set on the chart itself** — e.g. `<BarChart responsive width="100%" height={320}>`. `responsive` keeps the width fluid; the height must be an explicit number because a chart has no intrinsic height. Put these on the chart, not a parent `<div>` — Recharts draws to the chart's own box, so a parent's height does not flow in and a bare `<BarChart responsive>` collapses to nothing. Do not use `ResponsiveContainer`. - **Give the Y axis headroom — the tallest value must never touch the top of the frame.** Recharts otherwise caps the domain at the data's max, so the biggest bar or point runs into the top edge. On bar/line/area, set `domain={[0, (max) => Math.ceil(max * 1.1)]}` on the `<YAxis>`: keep the baseline at 0 and round the top up past the tallest value. Pie/donut have no axis, so this does not apply. - **Take every color and label style from `useArtifactTheme()`** — never a hardcoded hex, a raw `var(--color-*)`, or an opacity/tint variant. `const { charts } = useArtifactTheme()` gives the color groups below plus `charts.axis`, `charts.grid`, `charts.legend`, `charts.tooltip`, and `charts.cursor`; spread each onto the matching Recharts prop (`fill`, `stroke`, `tick`, …). Put `stroke={charts.axis.line}` on every `<XAxis>`/`<YAxis>` — without it Recharts paints its `#666` default axis line. Color must encode something — if it doesn't, don't spend it; most charts are single-series and monochrome. Pick the group by this decision tree, top to bottom, stop at the first match: 1. **Positive/negative or good/bad state** (won vs lost, on-target vs at-risk, period delta) → the semantic set: `charts.positive`, `charts.negative`, `charts.neutral` (excluded/no-value). If a chart uses semantic colors, every series in it is semantic — never mix semantic and categorical. 2. **Ordinal dimension** (stage, priority, tier, score/size band, an age or amount bucket like "51-250" or "1K-5K") → `charts.sequential[i]`, light to dark. This holds even for a single series — a lone bar or line over an ordinal dimension is sequential, NOT `primary`. Order the axis by the dimension's own sequence (1-10 → 100K+, P0 → S4), never by the measure, so lightness climbs monotonically down the axis; spread across the ramp rather than clustering (e.g. steps 0, 2, 3, 5). Steps 0–2 are fills only — never lines or points. Never put a categorical color on an ordinal dimension. 3. **More than one series in the same space** (stacked/grouped bar, multi-line, stacked area, pie, donut, treemap) → `charts.categorical[i]` in order. Six distinct colors; beyond six categories, wrap with `charts.categorical[i % 6]` so colors repeat rather than run out. `charts.other` is reserved for "Unknown"/"No value"/excluded categories only — never a real category past the sixth — and always sits last in stack and legend. 4. **Everything else** → a single `charts.primary`. When in doubt, this. Assign deterministically so the same data yields the same colors on every render and a category keeps its color across a dashboard. For categorical and `primary`, sort rows by the charted measure descending, then assign in token order. For a sequential/ordinal chart, order rows by the dimension's natural sequence instead (rule 2), not the measure, so the ramp reads in order. This row order sets the legend order too — the legend follows row/series order. The precedence in general: order by rank (the charted measure, descending); if there is no measure to rank by, keep the data's natural order; fall back to alphabetical only as a last resort, when neither exists — never sort categories alphabetically by default. When a chart plots more than one series, give each a `name` and add `<Legend iconType={charts.legend.iconType} wrapperStyle={{ color: charts.legend.text, fontSize: charts.legend.fontSize }} />`. State the rule you applied when explaining a generated chart ("single series, so primary"). See the `@clarify/ui/artifact-theme` entry above for the full pattern. - **Give pie/donut slices a blended border.** Spread `stroke={charts.pieStroke} strokeWidth={1}` onto each `<Cell>` — a half-opacity separator that reads in both light and dark. Never set a solid white stroke; it looks wrong on a dark background. - **Render the tooltip as `<ChartTooltip />` (from `@clarify/ui/chart-tooltip`) directly inside the chart** — it IS the Recharts `<Tooltip>`, already framed. Never pass it to another element's `content` (e.g. `content={<ChartTooltip/>}`): `ChartTooltip` is the Tooltip, so nesting one inside a Tooltip's `content` recurses without end and crashes the report. - **Don't bucket a metric by time unless the user asked for that grouping.** Reach for a time `GROUP BY` (`toDate(timestamp)`, `toStartOfWeek/Month(…)`) ONLY when the request names the granularity — "by month", "per week", "grouped by day", "weekly", "monthly". "Over time", "trend", or "as a line chart" is NOT that request: a time series already IS a trend, so it can't be the trigger. By default show a single aggregate over the report's window — "deals created", not "deals created per month" — and let the report's date filter (`timeRange`, above) set the period. Grouping by a non-time category (stage, owner) is unaffected. - **Compare two periods on a line chart by default.** A single-measure line chart over the window should almost always show the prior period too, so fetch with `compareToPrevious` and draw it as a second series: pair `query.rows[i]` with `query.previousRows[i]` into one data array (`{ bucket, current, previous }`) and plot two `<Line>`s. Color them `charts.categorical[0]` / `charts.categorical[1]` (never hardcode); a dashed previous line (`strokeDasharray`) reads as the baseline. This index pairing is chart data shaping, not the banned in-code aggregation. Skip the overlay only for a multi-series chart (a breakdown already uses the series slots) or a non-time category chart. ## The `analytics.event` table (ClickHouse) Read-only SQL runs against ClickHouse, not PostgreSQL — use ClickHouse syntax (`JSONExtractString`, `toDate`, `argMax`, etc.). Every CRM record lives in ONE append-only CDC event log, `analytics.event` — NOT a table of current records; every create/update/delete is its own row. There is no `deal` / `company` / `person` table (`FROM deal` fails with "Unknown table expression identifier"). Always query `FROM analytics.event` and pick the entity with `WHERE entity_type = '<type>'`. Hot keys are promoted to materialized columns (below); every other field is read from `properties` with `JSONExtract*`. Every event carries a FULL snapshot of the record's fields in `properties` — create, update, and delete alike. An update is not a delta: it repeats every field the record has, not just the ones that changed. So the single latest event per entity already holds every current field, and you never need to stitch fields together across events. (The one exception: a field you can't access is absent from `properties`.) - `entity_type` (String) — Subject type: `deal`, `company`, `person`, `meeting`, `message`, or `c_<slug>` for a custom object - `entity_id` (String) — Subject record id - `type` (String): `clarify:create`, `clarify:update`, `clarify:delete`, or `clarify:merge` (an update to the record that survived a merge; the merged-away records get a `clarify:delete`) - `timestamp` (DateTime64(6,'UTC')) — Event time; use `toDate(timestamp)` for day grouping - `properties` (String/JSON) — A full snapshot of the record's fields at event time (every field, not just the changed ones); read with `JSONExtractString/Float/Bool(properties, '<field>')` - `diff` (String/JSON) — On update events, the field-level changes this event applied: a JSON array of `{op, path, val, oldVal}` (`path` locates the field, `oldVal` → `val` is the transition). Empty (`''`) on create and no-op events. Use it to detect WHEN a field changed — see "Detecting when a field changed" - `actor` (Tuple): `actor._id`, `actor.entity`, `actor.source_id` (all String, native paths, no `JSONExtract` needed); usable in `GROUP BY` / `ORDER BY` - Use `actor.entity` and `actor.source_id` to tell an automated actor (an agent or an API key) from a human user, and group or exclude by them when an automation may skew a metric - `m_stage` (String) — Materialized `JSONExtractString(properties,'stage')`; empty if absent - `m_amount` (Float64) — Materialized `JSONExtractFloat(properties,'amount')`; `0` if absent - `m_close_date` (Nullable(Date)) — Materialized `toDateOrNull(properties.close_date)`; `NULL` if absent/unset. A native date — range-filter and group it directly (`m_close_date >= '2026-01-01'`, `toStartOfMonth(m_close_date)`) with no `toDate` wrapper ### Reading fields is ClickHouse, not PostgreSQL PostgreSQL JSONB operators `->` and `->>` do not exist in ClickHouse — `properties->>'description'` fails. Read fields with `JSONExtractString(properties, 'description')` (or `JSONExtractFloat` / `JSONExtractBool`). There is no `JSONExtractFloat64` — use `JSONExtractFloat`. If a query fails because a function does not exist, use the alternative ClickHouse suggests (e.g. `JSONExtractRaw`). ### Materialized columns Prefer the materialized columns `m_stage` / `m_amount` / `m_close_date` over `JSONExtract*(properties, 'stage'|'amount'|'close_date')` when the key matches — they are typed, indexed, and skip a JSON parse per row. They are populated from whatever `properties.stage` / `properties.amount` / `properties.close_date` carries on each row, regardless of `entity_type`, so they work for a custom object with those fields too. For `m_stage` / `m_amount`, empty / `0` means the event didn't carry the key. `m_close_date` instead uses `NULL` for an absent or unset close date (a date has no neutral sentinel), so test presence with `m_close_date IS NOT NULL`, not `!= ''`. `m_stage` (like every snapshot field) is the value the record held *when the event fired*, not a transition. Counting `m_stage = 'Won'` answers "records that were in Won while something happened to them" — an enrichment sweep, a note, or an owner change re-emits the unchanged stage — so it tracks activity, not outcomes. For "records that *entered* a stage", read `diff` instead (see "Detecting when a field changed"). ### Write fast queries - Always filter by `entity_type`; add `entity_id` for single-record questions. Events are stored in that order, so these filters read a small slice. Filtering only on other columns (`type`, `m_stage`, `m_amount`, `m_close_date`, any `JSONExtract*` value) scans every entity. - Bad: `SELECT count() FROM analytics.event WHERE m_stage = 'Won'`. - Good: `... WHERE entity_type = 'deal' AND m_stage = 'Won'`. - Give time-series, activity, and trend queries a `timestamp` range (`timestamp >= now() - INTERVAL 90 DAY`) to scope the report and bound the scan. Current-state reconstruction is the exception (below): it needs each entity's full history, so do NOT put a `timestamp` floor on it. - Name the columns you need, and avoid `SELECT *`: it computes the `properties` JSON for every row. - Bad: `SELECT * FROM analytics.event WHERE ...`. - Good: `SELECT entity_id, timestamp, m_stage FROM analytics.event WHERE ...`. - Group by low-cardinality columns (`entity_type`, `m_stage`, `toDate(timestamp)`, `entity_id`). Grouping by a freeform `JSONExtractString(properties, '<field>')` of a note or free text parses JSON per row and explodes the group count. - To eyeball a few recent rows, use `ORDER BY timestamp DESC LIMIT <n>`. - Date literals: prefer relative helpers (`now() - INTERVAL 1 MONTH`, `toStartOfMonth(now())`, `today() - 7`). You have no reliable wall clock, and a hardcoded boundary silently drifts. A bare `timestamp >= '2026-04-01T00:00:00Z'` rejects the ISO `T`/`Z`; use space-separated `'2026-04-01 00:00:00'`, `parseDateTime64BestEffort('2026-04-01T00:00:00Z')`, or `CAST('2026-04-01T00:00:00Z' AS DateTime64(6, 'UTC'))`. ### Reconstruct current state from the log To report on CURRENT state, rebuild it from the event history: - Every event stores a full snapshot of the record, so reconstruct current field values with plain `argMax(<field>, timestamp)` grouped by `entity_id` — never a `JSONHas` / `<field> != ''` / `!= 0` presence guard, which resurrects a stale earlier value for a field that was later cleared or set back to 0. Read a JSON field with `argMax(JSONExtractString(properties,'<field>'), timestamp)`, or a materialized column directly with `argMax(m_stage, timestamp)`. - Drop deleted records: `HAVING argMax(type, timestamp) != 'clarify:delete'`. - Reconstruct in a CTE, then filter/aggregate over the CTE — filtering a mutable field inside the per-entity scan changes which event counts as "latest" and produces wrong totals. ```sql WITH deal_current AS ( SELECT entity_id, argMax(m_stage, timestamp) AS stage, argMax(m_amount, timestamp) AS amount FROM analytics.event WHERE entity_type = 'deal' GROUP BY entity_id HAVING argMax(type, timestamp) != 'clarify:delete' ) SELECT stage, count() AS deals, sum(amount) AS pipeline FROM deal_current WHERE stage NOT IN ('Closed Won', 'Closed Lost') GROUP BY stage ``` ### Count stage transitions in a period A snapshot count (`m_stage = 'Won'`) can't answer "how many deals were won this quarter" — it counts deals *touched* while already won. Count the transition instead: the events where `stage` moved into a closed value, plus deals created directly in one. The `UNION` branch is required because `diff` is empty on create — it catches deals imported straight into a closed stage. ```sql -- Deals that ENTERED a closed stage inside the window. WITH closed AS ( SELECT entity_id, timestamp, m_stage AS stage_at_event FROM analytics.event WHERE entity_type = 'deal' AND type = 'clarify:update' AND arrayExists(d -> JSONExtractString(d, 'path', 1) = 'stage' AND JSONExtractString(d, 'val') IN ('Won', 'Lost'), JSONExtractArrayRaw(diff)) UNION ALL -- diff is empty on create: catches deals imported directly into a closed stage SELECT entity_id, timestamp, m_stage FROM analytics.event WHERE entity_type = 'deal' AND type = 'clarify:create' AND m_stage IN ('Won', 'Lost') ) SELECT countIf(final_stage = 'Won') AS deals_won, count() AS deals_closed, countIf(final_stage = 'Won') / nullIf(count(), 0) AS win_rate FROM (SELECT entity_id, argMax(stage_at_event, timestamp) AS final_stage FROM closed GROUP BY entity_id) ``` The outer `argMax` collapses each deal to its last transition in the window, so a deal that goes Won → Lost inside it counts once, as Lost. There is no delete guard here on purpose — a deal won in the window was won even if the record was later deleted; to drop since-deleted deals, reconstruct current state (above) and keep only the `entity_id`s that are still live. Matching on `val` works when you can access the field; for one you can't, `val` reads `'REDACTED'` (its `path` is kept), so match on `path` presence alone. For a "closed per month" trend, bucket by the event `timestamp` — that is when the transition actually happened. One data limitation to surface, not hide: on a batch-imported workspace every `clarify:create` lands on the import date, so deals that closed before they were imported collapse onto that date — the log has no real historical close date for them. `m_close_date` does not fill that gap: it is the *expected* close date (often in the future), right for a pipeline-by-expected-close forecast but wrong as a "when did we win" bucket. When you do bucket a retrospective metric by a date field that can run into the future (`m_close_date`, any custom date field), cap the buckets to the current period — `AND m_close_date <= today()`, or `HAVING bucket <= toStartOfMonth(today())`. A future bucket holds only open pipeline, so a "what happened" metric (win rate, deals won) reads there as losses or zeros. Drop the cap only for an intentional forward-looking pipeline/forecast. ### Detecting when a field changed A field being non-empty on an event does NOT mean it changed on that event — every event repeats all fields, so an edit to one field re-emits the rest unchanged. Use the `diff` column: on an update it lists exactly the fields that changed, so "did this field change on this event" is a plain row filter. Unlike comparing snapshots across events, this composes with a `timestamp` range and stays fast. A field changed on an event when `diff` holds an entry whose first `path` element is that field: `arrayExists(d -> JSONExtractString(d, 'path', 1) = 'stage', JSONExtractArrayRaw(diff))`. The matching entry also carries the transition — `oldVal` → `val` — so you can report "moved from X to Y" without reading other events. Caveats: `diff` is populated on `clarify:update` events only — it is empty on `clarify:create`, so if you also need the value set at creation (e.g. a deal's first stage), `UNION` in the create event. A change to a field you can't access shows `val`/`oldVal` as `'REDACTED'` but keeps its `path`, so the change is still detectable. Do NOT count a stage question off the snapshot: `m_stage != ''` counts every edit to a record that has a stage, and `m_stage = 'Won'` counts every edit to an already-won deal — neither is a stage change. Match on `diff` instead (see "Count stage transitions in a period"). ### Join across entities Every entity lives in the same `analytics.event` table, so a cross-entity report is CTEs joined on a foreign key stored in `properties`. Reconstruct each entity's current state in its own CTE (the pattern above), then join on the id — a deal's `company_id` links to the company's `entity_id`. Scope the looked-up CTE to only the ids the join needs: add `AND entity_id IN (SELECT <fk> FROM <driving_cte>)` to its `WHERE`. `entity_id` is a sort-key column, so this prunes reconstruction to a tiny slice instead of rebuilding every record of that entity type — the difference between a many-second and a sub-second query. ```sql WITH deal_current AS ( SELECT entity_id, argMax(JSONExtractString(properties,'company_id'), timestamp) AS company_id, argMax(m_amount, timestamp) AS amount FROM analytics.event WHERE entity_type = 'deal' GROUP BY entity_id HAVING argMax(type, timestamp) != 'clarify:delete' ), company_current AS ( SELECT entity_id, argMax(JSONExtractString(properties,'name'), timestamp) AS name FROM analytics.event WHERE entity_type = 'company' AND entity_id IN (SELECT company_id FROM deal_current) GROUP BY entity_id HAVING argMax(type, timestamp) != 'clarify:delete' ) SELECT c.name AS company, sum(d.amount) AS pipeline FROM deal_current d JOIN company_current c ON c.entity_id = d.company_id GROUP BY c.name ORDER BY pipeline DESC ``` ### Common pitfalls - Summed or counted returned rows by hand: you totaled values in your reasoning instead of in the query. Push it into the query (`sum(...)`, `count()`, `avg(...)`, `countIf(...)`) over the reconstructed CTE, and read the total from the result. - Pasted a literal id list into `IN ('…','…')`: you transcribed ids from a prior result. Filter with a subquery instead: `entity_id IN (SELECT <fk> FROM <cte>)` (the join pattern above). ## Postgres source — current record state Pass `useQuery(sql, { source: 'postgres' })` to read current record state straight from Postgres — the values as they are now: deals in each stage right now, counts and sums of present field values. Use it when the question is about the present. For history, trends, point-in-time, or stage transitions, use the ClickHouse source instead — Postgres holds no history. - The schema is per-workspace and is NOT included here. Call `get-schema` (format "read") for the entities you need before you write SQL, then prove the query with `query-data`. - Query each entity by its table name (`deal`, `person`, `company`, …). The primary key is `_id`; audit columns are `_created_at` / `_updated_at`. - Many columns are JSONB — use `->` / `->>`. A name stored as `{first_name, last_name}` needs `->>`, not a bare ILIKE. Multi-select and label arrays are `{items: string[]}`; test membership with `?|` (`(person.labels -> 'items') ?| ARRAY['ICP']`), never `@>`. - To-one links are foreign-key columns (`deal.company_id`, `deal.owner_id`); many-to-many links go through join tables named by the two entities in alphabetical order (`person_deal`, `person_meeting`). - Postgres holds current values only — there is no history or point-in-time. Do NOT pass `timeRange` to a Postgres query — it is rejected. Write explicit date `WHERE` filters instead. For stage transitions, past values, or trends over time, use the ClickHouse source. ## Keep queries simple Prefer several small, focused queries (one per section) over one large multi-join — it fits the per-section loading/error model above, so one slow or failed query never blanks the sections that are ready. When a query uses a time window, state the window in the UI so the reader knows the period and as-of date, and whether it is a fixed snapshot (absolute dates) or a rolling window (relative, recomputed on each open). A table is not pinned to one query. To add a column to a table already in the artifact, edit that table — never add a second table beside it. Update the existing artifact with `artifact_id` and `edits`. First choice: widen that table's query — project the new column, or JOIN it in when it lives in the same source (see the cross-entity JOIN guidance above) — and add the matching `DataTable` column. Fallback, only when one query cannot return the column (a different source, e.g. a Postgres current-state table plus a ClickHouse stage-history metric, which cannot JOIN): run a second `useQuery`, build a lookup keyed by `entity_id` from its rows, map the first query's rows onto it to attach the column, and pass the combined array to the one `DataTable`. ## Dashboards When `type` is "Dashboard", the report is a multi-section overview. Its sections can be ClickHouse (event / time-series), Postgres (current record state), or a mix of both in the same dashboard. Design it metric-first: for each section ask "what does it answer when the viewer changes the window?" A section that only makes sense at one fixed window is the wrong shape. When the ask is about change over time, prefer a dynamic, date-filterable ClickHouse section (the event log, scoped by `timeRange`) over a static Postgres current-state snapshot — a snapshot can't move with the window. - Lead with a `@clarify/ui/dashboard-header`. Add a `@clarify/ui/filter-bar` holding a `@clarify/ui/date-range-picker` **when any section has a ClickHouse query the range can scope.** The picker drives `timeRange`, which applies to ClickHouse only — so it scopes the dashboard's ClickHouse sections and its Postgres sections ignore it. Omit the picker only when *every* section is Postgres, since it would then scope nothing. When you include it, it defaults to the last 30 days — keep that default unless the report needs another window, then pass `defaultQuickSelect` (e.g. `"Last 7 days"`). - When present, the picker is the dashboard's time control. Hold its `onApply` payload (`{ from, to, previous }`) in React state and pass it to each ClickHouse section as `useQuery(sql, { timeRange: range })`, so those sections re-filter when the viewer changes the period. Never fetch all rows and filter in the client, and never interpolate the dates into the SQL. (Postgres queries ignore `timeRange` — see "Fetching live data".) - **A dashboard is the strongest case for trends — its whole point is change-over-time against a chosen window.** Pass `compareToPrevious: range.previous ?? true` on essentially every KPI tile and single-measure line chart, so each `MetricBlock` shows its `TrendIndicator` and each trend line carries its prior-period baseline. A dashboard where the KPIs show a bare number with no trend is the wrong default. - Before adding a time-bucketed chart (a `GROUP BY` month/week), ask: if the viewer picks "Last 7 days", does it still render a useful answer? A weekly bar chart over a 7-day window is one bar. A time-scoped section usually answers "is this better or worse than before?" — that's a KPI with comparison (a `MetricBlock` with `compareToPrevious`), not a time-bucketed bar chart. Reach for the bucketed chart only when the user asks for a trend by period (see the time `GROUP BY` chart rule above). A pipeline-health dashboard leads with a KPI strip that answers the window's headline questions, each a comparison — deals won, win rate, pipeline created: ```tsx const range = /* the DateRangePicker's applied { from, to, previous } */; const won = useQuery(dealsWonSql, { timeRange: range, title: 'Deals won', compareToPrevious: range.previous ?? true, }); // winRate is the same shape with format="percent"; pipelineCreated with format="currency" return ( <div className="grid grid-cols-3 gap-4 p-6"> <MetricBlock title="Deals won" query={won} value={won.rows[0]?.deals_won} format="number" comparison={{ field: 'deals_won', label: 'vs previous period' }} // Detail SQL must project name, entity_id, entity_type — read literally // off each row; any other alias silently drops the link (see Block docs) underlyingQuery={{ sql: dealsWonDetailSql }} /> {/* win rate, pipeline created — same shape */} </div> ); ``` ## Building a deck A deck is the artifact for anything the user will present or walk someone through: they ask for a deck, slides, a QBR, a pitch, or a board or team readout. A dashboard is for watching numbers move against a window; a report is for reading. When the ask is "present", build it with `@clarify/ui/deck` (`Deck`, `Slide`, `SlideData`, `Steps`, `Step`) and fetch its props with `get-artifact-component-doc` like any other component. - **Hoist every `useQuery` to the top of `ArtifactContents` and pass the results into the slides. Hard rule.** Only the on-screen slide is mounted, so a `useQuery` inside a slide refetches and shows a skeleton on every visit. - **The canvas.** Each `Slide` is an empty 960×540 design-px canvas, scaled to fit the viewer. It clips and never scrolls, so anything past its edges is cut off. You compose the whole slide: the inset, the alignment, the type, the color, the hierarchy. Design each slide like a designer would, not like a document: one idea, one focal point, generous margins (`p-12` to `p-16`), and few words. - **Type on a slide.** The slide sets its own type scale, so the text components render at slide size with no size classes: `CaptionText` for an eyebrow (14px, add `uppercase tracking-wider`), `Text` for body (16px), `Heading2` for a subtitle (24px), `Heading1` for a slide title (32px), `DisplayText` for a big title (44px). Three display sizes exist only on slides, through the `size` prop: `text-4xl` (56px) for a cover title, `text-5xl` (72px), and `text-6xl` (86px) for a headline number, where you wrap the `MetricValue` in `<Text as="div" size="text-6xl">`. Never write a raw text-size utility on a slide; pick the component or the `size`. - **Color on a slide.** Use the semantic utilities and nothing else: `text-fg-1` to `text-fg-4`, `bg-surface`, `bg-subtle`, `bg-muted`, `border-border`, the status tones (`text-danger`, `bg-success/10`), and the six accents (`text-accent-1`, `bg-accent-1/10`, `border-accent-1`, gradients `bg-gradient-to-br from-accent-1 to-accent-2`). A dark cover or section slide uses `bg-inverse` with `text-fg-on-inverse`, which flips with the surface. Never pair it with `text-fg-onbrand`, a fixed white that vanishes on the dark-mode inverse. Never a palette shade (`gray-700`, `blue-500`) or a hex: those ignore dark mode and the workspace palette. Backgrounds are allowed on slides. One accent moment per slide is plenty. - **Layout on a slide.** Flex, grid, and absolute positioning are all allowed inside a slide (`absolute inset-0`, `bottom-12 left-16`), with the standard spacing and sizing scale. Arbitrary values (`p-[37px]`) are not emitted, so stay on the scale. Never add a scroll container. - **Shape.** 6 to 12 slides. Open on a cover, divide chapters with a section slide, end on a closing. One idea per slide. Vary the layout across slides: alternate full-bleed, split, and metric-focal compositions so neighboring slides do not share a template. A deck where every slide is the same layout reads as filler. When content does not fit, split the slide; never shrink type to cram it in. - **Data on a slide.** Wrap a query-driven body in one `SlideData` (it takes the slide's `query` and `underlyingQuery`, same contract as Block) so the loading, error, empty, and refresh states render without a card. Inside it, build from `query.rows`: a `MetricValue` with `size="headline"` for a big number, a chart with `height` around 260 to 320, or a `DataTable`, which scrolls inside the slide, so return every row the story needs. A `Block` or `MetricBlock` is also fine when a card is what you want. - **A deck shows live data, with no controls.** Every query runs again each time the deck opens, so never call it a snapshot and never write "as of" with a date you typed. State the window on the cover, computed: a quarter or a named period as text, a relative window from `new Date()`. Pass a fixed `timeRange` to each ClickHouse `useQuery` and add no `DateRangePicker` or filter bar. - **Every number in the deck comes from the rows.** A figure anywhere on a slide or in `notes` is interpolated from `query.rows`, never typed from a query you ran while authoring. A typed number is stale the next time the deck opens. - **`useSlidePageNumber()`** returns `{ current, total }`. Show the page number on every slide after the cover, placed consistently (a corner is usual). Slides must be direct children of `Deck` (fragments are fine; a component that renders slides is not). - **`Steps` / `Step`** when the order of ideas is the point: a slide that lists next steps, priorities, plays, or asks puts each one in a `Step` so it lands on its own click. Each `Step` must be a direct child of `Steps`. - **`notes`** carry what the presenter says on that slide, not a summary of it. - **Give the `Deck` a `title` and `className="h-screen"`** so it fills the frame. - **Set `type` to "Deck"** so the library shows it as a deck. - **Self-review before you save:** every `useQuery` sits above the `Deck`; every slide has one idea and nothing near its edges; every slide after the cover shows its page number and neighboring slides do not share a layout; type goes through the text components and color through the semantic utilities, with no palette shade or hex anywhere; the deck opens on a cover and ends on a closing; the window is stated; no typed number or date anywhere; "snapshot" appears nowhere. ## Building a document A document is the artifact for anything the user will read rather than watch or present: a business case, a prospecting brief, a proposal, a memo, an account plan, a one-pager. A dashboard is for watching numbers move; a deck is for presenting. When the ask is "write", build it with `@clarify/ui/document` (`Document`, `Section`, `Callout`) and fetch its props with `get-artifact-component-doc` like any other component. - **A document about the workspace's data uses live components, the way a dashboard does. Hard rule.** Hoist every `useQuery` to the top of `ArtifactContents` and pass the results into the sections. A section that makes a claim about numbers renders them from `query.rows` through a `MetricBlock`, a `MetricValue`, a chart, or a `DataTable` inside a `Block`, and a `Callout` or paragraph interpolates its figures from the rows, never types them. Static prose is for framing, recommendations, and narrative; anything the reader would want current comes from a query. A document about the user's pipeline, deals, accounts, or activity with no `useQuery` is the wrong build. - **Shape.** One `Document` with a `title`, a one- or two-sentence `description`, and `meta` badges (the date computed from `new Date()`, the audience, a status). Then three to eight top-level `Section`s, each with a plain `title`; nest a `Section` inside another for a subsection. The table of contents builds itself from the sections, so every heading is a `Section`, never a bare heading. Two levels of nesting is the usual limit; three is the most the sidebar lists. - **Prose is `Text` from `@clarify/ui/text` with `as="p"`.** The document sets its measure and leading. Three to five sentences each, one idea per paragraph. Emphasis inside a paragraph is a nested `Text` with `as="span"`, `size="inherit"`, and `weight="font-medium"`, so it stays inline. An email address, URL, or phone number in prose is a `LinkText` from `@clarify/ui/text` with `href` (`mailto:` for email, `tel:` for a phone number), never plain or bold text. A list is a `ul` or `ol` with `list-disc` or `list-decimal`, `pl-5`, and `flex flex-col gap-2`, each item a `Text as="li"`. A nested list sits inside an item with `mt-2` and switches to `list-[circle]`, or `list-[lower-alpha]` for an `ol`. Never write a raw `<p>` or heading tag. - **Asides.** `Callout` with a `tone`: `info` for a recommendation, `warning` for a risk, `success` for a decision or milestone, `danger` for a blocker, `note` (the default) for context. At most one or two per section. A customer's or stakeholder's words go in a `blockquote` with `border-l-2 border-border-strong pl-7 py-2`, holding a `Text` at `size="text-lg"` and a `Text as="cite"` at `size="text-sm"` with `variant="secondary"` and `not-italic`. - **Laying out data.** Each query-driven figure sits in a `Block` or `MetricBlock` inside the `Section` that makes the claim. Two to four blocks side by side use `grid grid-cols-2 gap-6` (or `grid-cols-3 gap-5`, `grid-cols-4 gap-4`) with each child in a `min-w-0` div; prose stays single column. A document is read at about 880px, so a chart's `height` stays at or under 320. A table of non-data content (a plan, an option comparison) uses `DataTable` from `@clarify/ui/data-table` with a plain `rows` array. - **Live dates.** Every query runs again each time the document opens, so never write "as of" with a date you typed and never call the data a snapshot. A figure typed from a query you ran while authoring is stale the next time the document opens. State the window in the `description` or a `meta` badge, computed. - **Give the `Document` `className="h-screen"`** so it fills the frame and the sidebar can scroll with it. - **Set `type` to "Document"** so the library shows it as a document. - **Self-review before you save:** every `useQuery` sits above the `Document`; each claim about numbers renders from `query.rows`; every heading is a `Section`; every paragraph is a `Text`; the window is stated; no typed number or date anywhere; "snapshot" appears nowhere. ## Important notes Artifacts are read-only. `useQuery` runs SELECTs only; an artifact cannot create, update, or delete records or take any action. Do not build buttons, forms, or controls that mutate data, and do not tell the user an artifact will perform a write or an action — offer the closest thing you can actually do instead. When you tell the user about the artifact in chat, describe WHAT it shows and what it answers, not HOW you built it. Skip the CSS, query, and debugging details unless the user asks for them. This tool only persists the content or edits it is given; it does not generate or edit content itself. Author the full source, or the exact edit strings, yourself before calling this tool.

create-or-update-artifact

Create a new calendar event or update an existing one. ## When to use this tool - To create a new event: omit `event_id` and provide `title` and `when`. - To update an existing event: provide `event_id` along with the fields to change. ## When not to use this tool - This writes to the user's external calendar (Google / Microsoft) and can email invites. If the user means a custom object (one of the `entity` options on create-or-update-records, e.g. an "Events" object), create a record there instead. ## Important notes - Only the fields you provide are updated; omitted fields remain unchanged. - For recurring events, updates apply to the whole series. - `notify_participants` defaults to `true` on create (invite goes out) and `false` on update (so minor edits don't spam attendees). Set it explicitly when rescheduling or making changes attendees should know about. - When updating `participants`, the default is `add`: the listed emails are merged into the existing attendee list. To remove attendees, set `participants_mode` to `replace`: anyone not listed will be removed. - Get the user's timezone from get-current-user and pass it explicitly via `when.timezone` for timed events. Don't guess. - The write happens as soon as this tool is called, with no confirmation step. Confirm with the user first.

create-or-update-calendar-event

Create new fields or update existing field metadata (name, options, AI config) on any entity (company, person, deal, meeting, task, or custom object). When updating, send the field's current type. Only Text and Multiline text, or Number and Currency convert into each other. Its nullable/required status can't change. Also known as custom fields. Rename fields, add enum/select options (existing options are preserved; pass an empty options array to clear all), rename an option in place, change option colors, and configure AI autofill. Supports all field types: text, number, currency, date, enum, multi-select, markdown, attachment, and relationships. You must use `read-context` with context="field-docs" before creating or updating fields to load field type guidelines, AI prompt writing instructions, and examples. ## Important notes - To rename an enum option, send the new label as `value` and the current label as `previousValue`. Records keep their value and follow the rename. Without `previousValue`, a changed label adds a separate new option. - Field deletion is permanent. Clarify cannot restore or recover a deleted field. Never tell a user a deleted field can be brought back. - If a user asks to restore or undelete a field, explain it can't be recovered and offer to create a new field with that name instead: it will be a fresh, separate field. ## Board / Kanban views group by an existing field A board (Kanban) view groups records into columns by one specific enum field, usually the object's built-in `status` field, or the field configured for that board. Creating a new enum field (e.g. a custom `stage`) does NOT change which field the board groups by, and you cannot see a view's board-grouping configuration from here. - When a user wants records to move between board columns, set values on the field the board already groups by (commonly `status`), or ask the user which field the board should group by. Do not create a parallel new enum and tell the user the board will use it. - If records don't land in the expected column but the data reads back correctly, do not blame a display, refresh, or caching issue. The likely cause is that the board groups by a different field than the one you set.

create-or-update-fields

Create or update a dynamic list: a saved view whose membership is defined by a SQL query. Dynamic lists are the only list type Clarify supports today. ## When to use this tool - To create a new list: omit list_id and provide title + sql - To update an existing list: provide list_id along with the fields to change - When creating a new list, always set an emoji: a single emoji that represents the list's theme (e.g. "💰" for a deals list, "🎯" for priority accounts, "📅" for a meetings list). The emoji goes only in emoji; never prefix title with it, since the list already renders the emoji next to its title When the user is viewing a list and asks to show, filter, narrow, or sort what they see ("show me just X", "filter to Y", "without Z"), update that list: pass its list_id and the full SQL built from its current definition. The update is staged as a draft, so it does not change the live list for anyone until the user applies it. Create a new list (omit list_id) only when the user asks for a new or separate list. Only pass title with a list_id when the user explicitly asks to rename it. A list is the right surface when the user wants a browsable, filterable set of records of one object type. If they want aggregations, charts, or a multi-part deliverable, that is a report or dashboard (`create-or-update-artifact`), not a list. If the user explicitly asked for a list, build it without asking; if they asked for a report but the result is really just a list of records, offer the list and explain the distinction first. ## If the user asks for a "static list" or to manually curate a list Static lists are deprecated. Clarify no longer offers them as a list type, although some legacy static lists may still exist in the workspace. Do not call this tool to create one. Tell the user static lists are no longer supported, then offer the workaround: add a label to the records they want to track, and create a dynamic list that filters on that label. All built-in entities (companies, people, deals) have a built-in `labels` field with color-coded user-defined values, so the user can add or remove the label to control list membership manually. ## SQL restrictions This tool supports a restricted SQL subset. The query is used for both display and counting (via COUNT(*) wrapping), so certain patterns are incompatible: - **SELECT ***: Use explicit, table-qualified column names (e.g., "SELECT person.name, person.email_addresses FROM person") - **DISTINCT ON**: Not compatible with COUNT(*) wrapping. Use GROUP BY for deduplication instead. - **CTEs (WITH ... AS)**: Not supported. Rewrite using JOINs or WHERE clauses. - **Subqueries in FROM**: SELECT ... FROM (subquery) is not supported. Query the table directly with WHERE/JOIN clauses. - **LIMIT / OFFSET**: Not supported. A dynamic list is a continuously-evaluated membership filter, not a ranked snapshot; the LIMIT is dropped during evaluation, so a "top N" query silently matches every qualifying record. To bound a list, narrow membership with a WHERE clause (e.g. a recency window like "meeting.start > NOW() - INTERVAL '30 days'") or have the user add a label and filter on it. ORDER BY is fine; it sets the default sort, not membership. - Column names must be table-qualified (e.g., "person.name" not just "name") - Aggregate functions in ORDER BY or HAVING must also appear in the SELECT clause - **Filtering labels / multi-select fields**: these store JSONB as `{items: string[]}`. Filter membership with the array-overlap operator, e.g. `(person.labels -> 'items') ?| ARRAY['BDR Prospect']`. Do not use the `@>` containment operator; it works in the database but the list UI cannot render or edit a filter built with it. - **Combining AND and OR**: Wrap each OR (or AND) group in parentheses, e.g. `WHERE company.industry = 'SaaS' AND (company.city = 'Boston' OR company.city = 'Austin')`. Never mix AND and OR at one level without parentheses: `a OR b AND c` runs as `a OR (b AND c)` and the list UI cannot edit it. The list UI edits one level of groups only: each group holds two or more plain conditions joined by a single AND or OR, and groups cannot contain other groups. Deeper nesting still runs but shows as an uneditable advanced filter. ## Filtering by the current user To make a list relative to whoever is viewing it (e.g. "my tasks", "deals I own"), compare against current_setting('app.current_user_id', TRUE), which resolves to the viewing user's ID at query time so the list works for every viewer. - Use it directly in a WHERE clause: WHERE task.assignee_id = current_setting('app.current_user_id', TRUE) - Do not hardcode a specific user's ID, and do not use template tokens like {{current_user_id}}; they are not substituted and the list will match nothing. ## Important notes - Only the fields you provide will be updated; omitted fields remain unchanged - The tool validates both the main query and count query to ensure the list will work when opened - Creating a new list publishes it immediately. Updating an existing list (passing list_id with a new sql) does not publish: the change is saved as a draft version and stays not-live until the user applies it. Relay the apply link from the tool response and tell the user to review and apply it with "Save for everyone"; do not tell the user the update is already live. Metadata-only edits (title, description, emoji) apply immediately. - When updating an existing list's SQL, do not rebuild its membership from memory or a session summary. A large unexplained drop in matched records usually means the new query is incomplete (e.g. after a context reset); re-read the list's current definition and reconcile against it instead of treating the new SQL as authoritative. ## Column choice for list views Lists render one row per root record, so every SELECT column must belong to the root entity. Read the `list-docs` context (via read-context) for the column rules: the title alias, showing a to-one relationship (join `<root>$<fk_column>` and select its primary field aliased `<root>$<fk_column>:__object__`, never the bare `*_id`), and why many-to-many columns don't work in a list. After creating or updating a list: 1. Tell the user what was created or updated in a friendly, conversational way 2. Provide a clickable markdown link to open the list (the tool response will include this) 3. If the tool response includes a prefilled Lead Finder link (returned when a new company or person list matches 0 records), relay it: offer it as the way to fill the list, using the exact markdown link from the response 4. Keep your response concise

create-or-update-list

Create a new custom object type or update an existing one in the workspace. ## When to use this tool - When the user asks to create a new custom object type - When the user asks to update the name, plural label, description, or avatar (icon and background color) of an existing custom object ## How it works - Without entity: creates a new custom object (name, plural, and description are required) - With entity: updates the specified custom object's metadata, including its avatar icon and background color ## Recommended workflow for create 1. Discuss with the user what the custom object represents 2. Ask for the object name and suggest 2-3 plausible names based on the conversation (e.g., "Contract", "Ticket", "Project"). Confirm plural and description with the user as well. 3. Call this tool to create the object 4. Immediately call `create-or-update-fields` with the returned entity identifier to add fields ## Description guidance The description field is stored as AI context for this object type, directly influencing how AI understands and works with records of this type. A good description captures what business concept this object represents and how the team uses it. Before creating a new object, if the user has not provided a description, ask them for one. Work with them to craft a description that captures the object's purpose. Only proceed without a description if the user explicitly declines.

create-or-update-object