> ## Documentation Index > Fetch the complete documentation index at: https://docs.dovetail.com/llms.txt > Use this file to discover all available pages before exploring further. # CLAUDE # Working on the Dovetail help center This repo powers [dovetail.com/help](https://dovetail.com/help). It's a [Mintlify](https://mintlify.com/) site: pages are `.mdx`, navigation lives in `docs.json`, and merges to `main` deploy automatically. Read this before editing content. *** ## The one rule that matters most **Never state a product fact you haven't verified.** The help center is support-facing — a wrong plan name, UI label, or capability claim creates tickets and erodes trust. Marketing copy on dovetail.com is often ahead of what has actually shipped. Verify in this order: 1. **The product codebase** at `~/Code/platform` — the source of truth for UI labels, action names, and behavior. See "Checking the product" below. 2. **Other pages in this repo** — if an existing page states it plainly, you can repeat it. 3. **dovetail.com** — good for positioning and naming, but it may describe things that aren't live yet. If you can't verify it, leave it out and flag it. An incomplete page beats a confidently wrong one. ### Live contradictions to be careful about These are known conflicts between sources. Don't "resolve" them by picking whichever reads better — ask. * **Agent and Digital Twin invocation in Slack and Teams.** dovetail.com says you can talk to a Digital Twin in Chat, Slack, or Teams. `help/agents.mdx` says invoking an agent in Teams and Slack is "coming soon", and `help/chat/chat-in-slack-and-teams` documents only generic Ask Dovetail Q\&A. The docs currently claim Chat only. Agents *delivering output to* Slack, Teams, or email is separate and is documented. * **Plan entitlements.** Entitlement callouts state what a reader can buy today, so they name **Enterprise** only: "Available on the [Enterprise plan](https://dovetail.com/pricing/)." Retired plans are never named in them. Where behavior genuinely differs for customers still on a retired plan, describe it as "legacy paid plans" rather than naming Professional or Business. *** ## Current product positioning Dovetail is an **AI-native customer intelligence platform**, not a research repository. Research repository is one use case among several. The platform narrative is **Centralize → Analyze → Query → Act**: | Stage | Surfaces | | :--------- | :-------------------------------- | | Centralize | Integrations (40+), API, MCP, CLI | | Analyze | Channels, Projects, Dashboards | | Query | Chat, Search | | Act | Agents, Digital Twins, Docs | Lead with Agents, Digital Twins, and Channels. Projects is fully supported but is no longer the front door. ### Channels 1.0 vs 2.0 Channels 2.0 is **the default for new channels** and is still in beta. Channels created before 2.0 stay on 1.0. * **2.0 terminology:** **Ideas** (ranked, revenue-weighted groupings of feedback) and **Evidence** (the underlying data points). Documented in `help/channels/channels-beta.mdx`. * **1.0 terminology:** themes and topics. Documented in `help/channels/index.mdx`, which is explicitly labeled as the 1.0 experience. Don't rename "themes" to "ideas" in 1.0 content or in Projects — canvas clustering legitimately uses "themes". ### Terminology * **Insights → Docs.** The product object is a doc. Generic English ("uncover insights") is fine, as are API identifiers like `insight:read`, and a third party's own naming, like Productboard Insights. * **Magic → AI.** AI summaries, AI highlights, AI clustering, and Automation. The blue magic shuriken icon keeps its name — that's the actual UI element. * **Digital Twins** — both words capitalized. It's a product name. * **Taxonomy** is acceptable in a research operations or research repository context, where it's the practitioner's word for a shared tag and field structure. It is *not* how we describe the product or lead onboarding content — that framing is what the September 2026 audit removed. * **Research repository** is one use case, not the category. The category is customer intelligence platform. ### Plans Dovetail sells a **Free** plan and an **Enterprise** plan. There is no self-serve paid tier — Enterprise goes through Sales. Professional and Business are **retired**: existing customers keep them, but nobody can subscribe or resubscribe. Never present them as purchasable. #### What the Free plan actually includes Source of truth: `workspaces/libraries/app-lib/src/billing/productRestrictions.ts` in `~/Code/platform`. Two free definitions are marked `Status: Active` — `freeJul2025` (current) and `freeMar2024` — so check both before writing a Free claim. In that file `null` means unlimited and `0` or `false` means unavailable; `ProjectService` enforces it as `maximumProjects !== null && active_count >= maximumProjects`. On the current Free plan (`freeJul2025`): | Included | Not included | | :---------------------------------------------------- | :----------------------------------------------------- | | 1 project, 1 channel (1,000 data points), 1 dashboard | Contacts, Segments, Workspace analytics | | Unlimited transcription minutes, up to 2,000 seats | Workspace fields, workspace tag boards, templates | | Canvas view, charts, AI highlights, views and filters | Translation, custom vocabulary, transcription settings | | Search, public API and CLI, web links, VTT download | AI summaries in search, semantic search | | | User roles, so there is no free Viewer tier | | | Agents, beta features, nested folders, video redaction | Two traps this has already caused: * **"Paid seat" is a seat type, not a statement about paying.** On Free plans without user roles every user is assigned a paid seat, so "requires a paid seat" does *not* mean "requires payment". Say what a role can do, and add "On plans without user roles, any user can." * **Don't gate a page to Enterprise and then grant the feature on Free** in the same callout. The `free-plan-contradiction` linter rule catches this. *** ## Writing style Follow [benjaminhumphrey.com/style](https://benjaminhumphrey.com/style). ### Tone Boring is the target. This is enterprise help documentation: professional, matter-of-fact, concise, and clear. It is not marketing copy, and it is not an essay. These patterns read as AI-generated and don't belong here: | Don't | Do | | :-------------------------------------------------------------- | :---------------------------------------------------------------------- | | "The hard part isn't the analysis. It's making it findable." | "Studies remain findable when tags are defined at the workspace level." | | "Escalations reach the right person before they become a fire." | "An agent can notify an owner when a threshold is met." | | Punchy fragments. For emphasis. | Every sentence gets a subject and a verb. | | Rhetorical questions as headings | Headings that name the task | | Metaphors — "front door", "receipts", "the pile" | The literal thing being described | | "It's not X, it's Y" | A plain statement of what it is | | "unlock", "supercharge", "seamlessly", "empower" | The verb that says what happens | Value and ROI framing is welcome, but state it as an outcome, plainly. "Prioritization can be based on revenue rather than request volume" is the value claim — it needs no flourish. Never invent evidence for it: no statistics, percentages, time savings, or dollar figures that aren't sourced. Ground value in a mechanism the docs describe. If a sentence sounds like it was written to be quoted, rewrite it. ### Mechanics The rules that come up most here: * **US English always.** Organize, analyze, customize, center. Dovetail is Australian; the docs are not. * **Sentence case** for titles and headings. Proper nouns keep their capitals: Dovetail, Channels, Agents, Docs, Digital Twins, Slack, Jira. * **"and", not "&"** — except inside a third-party UI label you're quoting ("Attributes & Claims" in Entra). * Active voice. Short, varied sentences. Simple language over jargon. * Oxford comma. Em dash (—) for strong breaks. Curly quotes, never straight ones (straight quotes only in code and HTML attributes). * Spell out zero through nine; digits for 10 and up. * Never write "click here" — describe the destination. ### Titles * Keep sidebar labels **under \~26 characters** so they don't wrap to two lines. * Use `sidebarTitle` for the short label and `title` for the fuller, descriptive page heading when they need to differ. * No two pages should share a sidebar label. Two "Digital Twins" entries in one sidebar is a real bug that shipped once already. *** ## Structure `docs.json` groups are ordered deliberately: orientation, then connecting data, then value and impact, then core surfaces, then technical and administrative material. Within a group, the overview or index page comes first and everything else is alphabetical by sidebar label. Two content layers, and both matter: * **Feature reference** — organized by product surface, named the way people search ("Channels", "Highlights"). The bulk of the site. * **Outcome and use case** — goal-shaped pages like `help/voice-of-customer` and `help/agents-use-cases` that explain what you're trying to achieve and route down into the reference layer. Don't duplicate steps here; link to them. When you add a page, add it to `docs.json`. When you delete or move one, add a redirect in the same file. ### One home per topic Each procedure lives on exactly one page. Everything else links to it. The Docs content used to exist twice — `help/projects/docs` duplicated ten of the twelve sections in `help/docs/` — which meant two pages to keep in sync and two competing search results. The split now is: * `help/docs/*` — how docs work anywhere in the workspace: creating, editing, formatting, sharing, presenting, metrics. * `help/projects/docs` — only what's specific to docs inside a project: building one from your highlights, referencing project data, keeping those references current, project fields. Before adding a section, search for its heading elsewhere in the repo. If it already exists, link instead. ### Every page needs frontmatter ```yaml theme={null} --- title: "Page title" sidebarTitle: "Short label" # only when the title is too long for the sidebar description: "One sentence, 110-160 characters, sentence case, ends with a period." --- ``` `description` is the search snippet and the meta description — it is not optional. Don't add `og:image` unless the file actually exists on disk; the site-level fallback in `docs.json` is better than a broken path. Write real alt text on every image. Filename-derived junk ("Clean Shot 2026 07 16 At 15 14 55\@2x", "Hero Pn") is useless to screen readers and to search. Describe what the image shows, in 5–12 words. *** ## Before you commit ```sh theme={null} node scripts/lint-terminology.mjs # terminology, US English, retired plan names — exits 1 on error mint dev # local preview at localhost:3000 mint broken-links # internal link check ``` The linter masks code, links, URLs, and file slugs, so it won't flag a British spelling inside a filename like `organise-and-share-docs`. It checks: | Rule | Level | Catches | | :------------------------ | :---- | :------------------------------------------------------------------------------------ | | `retired-insights` | error | "an insight" and friends — the product object is now a doc | | `retired-magic` | error | "magic AI features", "AI magic" marketing phrasing | | `retired-positioning` | error | "research repository", "synthetic user" | | `retired-plans` | error | Professional or Business presented as purchasable, or named in an entitlement callout | | `free-plan-contradiction` | error | a page gated to Enterprise that also grants the feature on Free | | `curly-quoted-attribute` | error | `title=“x”` in JSX, which drops the page from the build | | `legacy-help-url` | error | dead `dovetail.com/help/*` links from the pre-Mintlify site | | `us-english` | error | British spellings | | `missing-description` | warn | pages with no `description` frontmatter | | `channels-themes` | warn | "themes" in Channels 2.0 content, where it should be Ideas | Deliberately **not** flagged, so don't "fix" these: * "Magic summary" and similar feature names — they may still be live product names. Confirm with product first. * A vendor's own object name, like "Usersnap feedback item". Also check that internal links and heading anchors resolve, and that any image you reference actually exists on disk. Links pointing at `dovetail.com/help/*` are usually stale — the current docs are at `docs.dovetail.com`, and root-relative paths (`/help/channels`) are preferred for internal links. *** ## Checking the product `~/Code/platform` is a 19GB Nx monorepo. Recursive `grep` and `find` across it are unreliable from a sandboxed shell — they can return nothing rather than failing loudly, so **a zero-result grep there is not evidence of absence**. Run a control search for a term you know exists before trusting a negative result. Narrow, targeted reads do work. Useful locations: * `workspaces/apps/zapier/src/creates` and `.../triggers` — Zapier action and trigger labels. This is how we learned the Zapier action is "Add Doc to Project", not "Create Insight". * `workspaces/apps/web-app/src/components` — UI components. * `workspaces/services/mcp` — MCP server. *** ## History worth knowing A large content audit ran in September 2026. It deleted the Academy (27 pages), the taxonomy-led onboarding track, "How Dovetail is organized", and several superseded duplicates including root-level copies of pages that had already moved into `help/agents/`. Two lessons from it: 1. **Terminology drift is the main failure mode.** Insights were renamed to Docs, and the docs took months to catch up — the rename was still half-finished across ten pages. The linter exists to catch the next one. 2. **Delete rather than caveat.** A page describing a migration to a plan that no longer exists is worse than no page. Remove it and add a redirect.