Documentation Index

Fetch the complete documentation index at: https://docs.datagenie.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

CLAUDE.md

​

Working Relationship

• Push back on ideas when you have good reason — cite sources and explain your reasoning.
• ALWAYS ask for clarification rather than making assumptions.
• NEVER lie, guess, or make up anything about the product or features. When in doubt, consult /god:discuss or ask the user.

​

About This Repo

​

Dev Commands

mint dev          # Local preview at http://localhost:3000
mint update       # Update Mintlify CLI

Node requirement: mint does not run on Node 25+. Use an LTS Node (20 or 22). Static validation (broken links, frontmatter checks) can be done with Python while waiting on an LTS install.

​

Repo Structure

docs.json                        # Mintlify config — navigation, theme, branding, redirects
CLAUDE.md                        # You are here
index.mdx                        # Homepage — docs index, mode: wide
how-datagenie-works.mdx          # Product mechanics — lifecycle, anatomy, personas
404.mdx                          # Custom not-found page

getting-started/
  quickstart.mdx
  core-concepts.mdx
  glossary.mdx                   # 20+ term AccordionGroup

foundations/                     # Positioning pages, load-bearing
  autonomous-insights.mdx
  hyperconnected.mdx             # a.k.a. Nirvana
  responsible-ai.mdx

features/
  top-stories/                   # 5 pages
  wisdom/                        # 5 pages
  go/                            # 3 pages
  explorer/                      # 4 pages (incl. data-playground)
  dashboards/                    # 2 pages
  datasets/                      # 2 pages
  rbac/                          # 2 pages

use-cases/                       # 6 playbook pages
  overview.mdx
  revenue-analytics.mdx
  pricing-leakage.mdx
  product-adoption.mdx
  customer-churn-risk.mdx
  sla-risk.mdx

security/
  overview.mdx                   # Short — links out to trustcenter.datagenie.ai

changelog/
  latest-release.mdx             # Single-page timeline, <Update> components

images/                          # Screenshots, diagrams, GIFs — semantic kebab-case names
logo/                            # dg-logo.svg, dg-logo-dark.svg

Do not recreate releases-notes/. Per-version deep-dive pages were folded into changelog/latest-release.mdx as <Update> blocks. Adding new releases = adding new <Update> blocks to that single file, not new per-version files.

​

Brand & Positioning (CRITICAL — read before editing content)

​

Colors (primary use)

​

Tagline, category, one-liners

• Primary tagline: “Do Nothing. Know Everything.”
• Descriptive tagline: “The Answers You Needed, Before You Ask.”
• Category: Autonomous / Agentic Analytics (NOT “BI tool”, “augmented analytics”, or “decision intelligence”).

​

The canonical arc

SHOW DATA → ANSWER QUESTIONS → DISCOVER WHY → GET EVERYTHING
                                    ↑ ↑ DataGenie's unique space ↑ ↑

​

The two superpowers

1. Autonomous Insights — 100,000s of metric combinations auto-tracked, connected When · Where · What · What Else · Why stories, no manual configuration.
2. HyperConnected Insights (Nirvana) — virtual aggregate-level joins across data sources. No ETL.

​

Feature one-liners (use verbatim on overview pages)

• Top Stories: “Connected anomaly narratives — When, Where, What, What Else, Why — ranked by business impact. No queries required.”
• Wisdom: “The agentic analytics assistant. Ask complex, multi-stage questions in plain English; Wisdom plans, executes, explains. Far more than text-to-SQL.”
• GO: “Onboard a dataset in natural language. Describe the business problem; GO returns KPIs, dimensions, SQL, and a ready-to-run blueprint.”
• Explorer: “Interactive, multi-dimensional exploration of any KPI across time, segments, and contributors.”
• Dashboards: “Conversational dashboards — pin any Wisdom answer or Story chart; set one as Quick Look.”
• Datasets: “Onboarded data sources with KPIs, dimensions, and domain knowledge that power every downstream feature.”
• RBAC: “Role-based access control over datasets, dashboards, and features.”

​

Lean in / avoid

​

Customer names — never in docs

​

Terminology to enforce

• GO (all caps) after first expanded mention (“GO — Guided Onboarding”)
• Top Stories (title case, always)
• Wisdom Skills (capital S; also valid: “Cognitive Skills” for the built-in ones)
• HyperConnected (one word, camel case) — the marketing name
• Nirvana algorithm — the technical name, for deeper pages
• QuickLook (one word, camel case)
• IOE = Insights Over Email

​

Wisdom terminology — strict

• Never describe Wisdom as any form of “BI” — not “agentic BI”, not “conversational BI”, not “AI BI”. DataGenie sits above BI; calling Wisdom BI shrinks it.
• Approved descriptors: “agentic analytics assistant”, “agentic assistant”, “agentic analytics”, “agent”, “multi-stage reasoning agent”.
• When contrasting with competitors, say Wisdom is “far more than text-to-SQL”, not “better BI”.

​

Adding a New Page

1. Create the .mdx file in the right directory (see Repo Structure).
2. Add its path to docs.json under the correct group.pages array (paths are relative, no extension).
3. Every page must have frontmatter with at minimum title and description.
4. Run python3 -c "..." broken-link check (example at the bottom of this file) before committing.

{
  "group": "Top Stories",
  "pages": [
    "features/top-stories/overview",
    "features/top-stories/your-new-page"
  ]
}

​

Frontmatter (required on every page)

---
title: "Feature Name"
sidebarTitle: "Short Title"       # optional — sidebar label if different from title
description: "One-line summary of what this page covers."
icon: "icon-name"                 # Lucide or Font Awesome icon name
mode: "default"                   # optional — default | wide | center | custom
---

​

Page modes (and when each fails)

• default — sidebar + auto-generated H1 + right-side TOC. The safe default for every feature page.
• wide — sidebar + auto-generated H1, no TOC, full-width content column. Good for: homepage, how-datagenie-works, changelog, pages with lots of media.
• center — no sidebar, narrow reading column. Useful only if the page is an isolated long-form article.
• custom — blank canvas. Warning: requires manual # H1 and a wrapping <div> for width control — BUT markdown headings inside raw <div> blocks often don’t render correctly, so avoid unless you’re willing to write everything in HTML. We tried it on index and changelog and reverted.

​

Frontmatter options we’ve used

• mode: "wide" on index, how-datagenie-works, changelog (videos + media)
• mode: "default" on every feature page, foundation page, use-case page
• No OG images currently — og:image per-page frontmatter was stripped until real 1200×630 PNGs exist. Don’t reintroduce unless the assets are real.

​

Standard Page Structure

​

Feature overview skeleton (LOCKED — do not rename headings)

1. Video embed (if available) — always first, before any markdown
2. ## What [Feature] is — one paragraph definition/purpose, opens with the god one-liner verbatim
3. ## When to use [Feature] — bullet list of use cases (not “when not to”)
4. ## What you get — <CardGroup> with 3–6 cards summarizing key capabilities
5. ## How it works — <Steps> walkthrough (was “How to [do the thing]” in older copy — the literal heading is “How it works”)
6. ## What's next — <CardGroup> linking to related features and at least one Foundation

​

Foundations page skeleton

1. Opening paragraph (what it is, in one sentence)
2. One conceptual contrast section (e.g., before/after <Columns>)
3. How / when / where it shows up (<CardGroup> + optional <Steps>)
4. Cross-link row to the other two Foundations + the relevant feature

​

Use Case page skeleton

1. ## The problem
2. ## What DataGenie autonomously detects (CardGroup)
3. ## How the pieces combine or ## How it works (Steps)
4. ## Relevant features (CardGroup)

​

Mintlify Component Library

No API documentation in this repo. Skip <ParamField>, <ResponseField>, <Expandable>, <Panel>, and <ResponseExample> — those are API-only.

​

Decision guide — which component to use when

​

Components used heavily in this repo

• <Update> — the single source of truth for release notes. Each block has label (slugified into anchor — e.g., v4.12 → #v4-12), description (“Date · Headline Theme”), and tags array. Full release content goes inside. Mintlify auto-generates RSS from these.
• <CardGroup cols={3}> — default feature-summary grid.
• <Steps> — every procedure.
• <Tabs> — analyst vs. admin views, or multi-variant flows inside a release.
• <AccordionGroup> — Glossary and FAQ-style content.

​

Embedding Videos (watchclueso.com)

<Frame>
  <iframe
    src="https://watchclueso.com/embed/VIDEO_ID"
    title="Descriptive title for accessibility"
    style={{ width: "100%", aspectRatio: "16 / 9", border: "0" }}
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowFullScreen
  />
</Frame>

​

Update component (changelog)

<Update label="v4.12" description="April 13, 2026 · Dual Timezone, Fiscal Calendar" tags={["Wisdom", "Dashboards"]}>
  ## <Icon icon="rocket" color="#304FFE" size={26} /> Headline theme

  Lead paragraph describing why this release matters.

  ### Highlights
  <CardGroup cols={2}>...</CardGroup>

  ### <Icon icon="..." color="#EDAF28" size={22} /> Feature name
  Detail with videos, Steps, Tabs, etc.

  ### <Icon icon="bug" color="#EDAF28" size={22} /> Bug fixes
  <CardGroup cols={2}>...</CardGroup>
</Update>

​

MDX Gotchas (learned the hard way)

1. Angle brackets in text break the parser. <region> as a placeholder → “Expected a closing tag for <region>”. Use concrete values (the Northeast region) or backticks.
2. Markdown inside raw <div> doesn’t parse headings. ## Heading inside a <div style="..."> wrapper often renders as literal text. If you need a custom container, use HTML tags (<h2>) inside it, or drop the wrapper.
3. mode: "custom" kills the auto H1. You must write # Title manually AND the markdown-inside-div caveat applies.
4. mode: "wide" hides the right-side TOC. The Mintlify Update component’s tag filter is part of that TOC. Trade-off: wider content = no right-rail tag filter. We compensate on the changelog with a top-of-page horizontal “Jump to a release” strip.
5. Raw HTML needs style={{ }} (JSX object form), not style="" (string form).
6. <Frame> wraps images AND iframes. Don’t put raw <img> or <iframe> at the top level.

​

Writing Style

• Write for business users (analysts, operators, VPs of Analytics) — not engineers.
• Use plain, direct language. Avoid jargon.
• Second-person voice: “you” — not “the user”.
• Present tense: “Top Stories shows…” not “Top Stories will show…”
• Active voice: “DataGenie ranks stories by impact” not “Stories are ranked by impact.”
• Keep descriptions concise — one sentence per card/step where possible.
• Feature names are always title-cased: Top Stories, Wisdom, GO, Explorer.
• Headings: sentence case (“Getting started”, not “Getting Started”).
• Add prerequisites at the start of any procedural content.
• Add descriptive alt text to every image — never Image, Screenshot, or the filename.
• Use relative paths for all internal links — never absolute URLs.
• Dates in lists, cards, or timelines: when month + year alone is ambiguous because multiple items fall in the same month, include the day (e.g., “Mar 18, 2026” not “Mar 2026”). If month + year is unique within the list, month + year is fine.

• Filler phrases: “It’s worth noting that”, “Simply”, “Please note”, “In order to”
• Editorializing: “This is a powerful feature” — document what it does, not how impressive it is
• Passive voice as a default — use it only when the actor is unknown or irrelevant

​

Cross-linking rules

1. At least one Foundation page (/foundations/*)
2. At least two sibling / related features
3. Its parent group where relevant (e.g., Wisdom sub-pages → Wisdom overview)

​

Images & Media

• Filenames: lowercase, hyphen-separated, semantic (top-stories-impact-sort.png, not ts1.png). When adding release-note screenshots, name them by what they show.
• Alt text: descriptive. “Smart Mode toggle in Top Stories”, not “Image”.
• Prefer external URLs when available — Clueso CDN for video-adjacent assets, product CDN for direct UI captures — rather than re-hosting.
• Store local images in /images/ only when no external URL exists.
• GIFs are fine for short UI interactions (≤5 MB, ≤10s).
• For dark/light mode variants (if you ever add them): className="block dark:hidden" on the light image, className="hidden dark:block" on the dark image.
• Do not reintroduce non-descriptive names like image-1.png, bug1.png, ts1.png. They were all renamed in the revamp.

​

Changelog Maintenance (the single file that matters)

1. Open changelog/latest-release.mdx.
2. Add a new <Update> block at the top (newest first).
3. Use label="v4.13" (or whatever). Slug becomes the anchor #v4-13.
4. Set description="April 30, 2026 · Headline Theme". Use full date if the month already has another release.
5. Add relevant tags={[...]} — pick from existing tag vocabulary: Wisdom, Top Stories, GO, Explorer, Dashboards, Datasets, Anomaly Detection, Multi Yhat, KPI Attribution, Nirvana, IOE, Scenario Planning, Business Events, Smart Mode, Deep Dive, Reliability.
6. Inside the block, structure:
   • ## <Icon icon="rocket" color="#304FFE" size={26} /> Headline
   • Lead paragraph (1–2 sentences)
   • ### Highlights CardGroup (3–6 pillar cards with brand-blue color)
   • ### <Icon icon="..." color="#EDAF28" size={22} /> subsections per feature — videos, Steps, Tabs, screenshots
   • ### <Icon icon="bug" color="#EDAF28" size={22} /> Bug fixes CardGroup
   • ### <Icon icon="screwdriver-wrench" color="#EDAF28" size={22} /> Other changes bullets (if applicable)
7. Also add a new card to the “Jump to a release” horizontal strip at the top of the page.
8. If the banner in docs.json should mention this release, update banner.content.

​

Content Strategy

• Match the page to what the user needs: task → how-to, learning → tutorial, concept → explanation (Foundations).
• Search for existing content before adding anything new — avoid duplication.
• Start with the smallest reasonable change; expand only if needed.
• Make content evergreen when possible.
• Prioritize accuracy and usability over completeness.
• No API documentation in this repo — skip all API-oriented components.

​

Git Workflow

• Branch for non-trivial work (recent large revamp was on docs-revamp).
• NEVER use --no-verify when committing.
• Ask how to handle uncommitted changes before starting a task.
• Commit in small contextual chunks — one concern per commit, clear subject line, bulleted body explaining the “why”.
• Commit message style: sentence-case imperative subject, no Conventional Commit prefix (matching existing history).
• Co-author line Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> on Claude-assisted commits.
• NEVER skip or disable pre-commit hooks.

​

Validation (run before PRs)

# Validate docs.json + check nav references exist
python3 -c "
import os, json
doc = json.load(open('docs.json'))
missing = []
def check(pages):
    for p in pages:
        if isinstance(p, str):
            if not os.path.exists(p + '.mdx'): missing.append(p)
        elif isinstance(p, dict) and 'pages' in p:
            check(p['pages'])
for tab in doc['navigation']['tabs']:
    if 'groups' in tab:
        for g in tab['groups']: check(g['pages'])
    elif 'pages' in tab:
        check(tab['pages'])
print('nav missing:', missing or 'none')
"

# Scan for broken internal links
python3 -c "
import os, re
mdx = []
for root,_,files in os.walk('.'):
    if '.git' in root: continue
    for f in files:
        if f.endswith('.mdx'): mdx.append(os.path.join(root,f))
valid = set('/'+f[2:].replace('.mdx','') for f in mdx)
broken=[]
for f in mdx:
    for i,l in enumerate(open(f),1):
        for m in re.finditer(r'href=\"(/[^\"#?]+)',l):
            u=m.group(1).rstrip('/')
            if u not in valid and not u.startswith('/http'): broken.append(f'{f}:{i} {u}')
print('broken:', broken or 'none')
"

​

Do Not

• Skip frontmatter on any MDX file.
• Use absolute URLs for internal links.
• Include untested or made-up code examples.
• Make assumptions about product behavior — ask or consult /god:discuss.
• Use <ParamField>, <ResponseField>, <Expandable>, <Panel>, <ResponseExample> — those are API documentation components, not used here.
• Mention real customer names in docs.
• Use #3C55F1, #2F6FED, or #F5A623 for anything — those are legacy colors.
• Reintroduce per-version release files under releases-notes/product/. The changelog is now a single page.
• Use mermaid on the home or how-it-works pages (tables and Steps carry that weight now).

​

DataGenie KB — how to use it from this repo

​

Reads — always via the MCP

• mcp__datagenie-kb__tree — list folder structure with title + description per page. Use to discover what exists.
• mcp__datagenie-kb__search — ranked BM25 search across all KB pages. First stop for topic-based questions.
• mcp__datagenie-kb__glob — find slugs by glob pattern (meetings/standups/2026-04-*, sales/prospects/**, customers/accounts/{lnrs,carvana}/**). Mirrors Claude Code’s Glob.
• mcp__datagenie-kb__grep — regex content search with output_mode (content / files_with_matches / count), optional path glob, case_insensitive, multiline, context_lines. Mirrors Claude Code’s Grep. Use this when you need an exact string, date, or identifier that BM25 search would rank poorly.
• mcp__datagenie-kb__query_docs_filesystem — fetch full MDX of specific slugs (with optional offset/limit for line-range pagination on large pages). Mirrors Claude Code’s Read.

​

Writes — through skills, never freehand

mcp__datagenie-kb__query_docs_filesystem({ paths: ["working-with-kb/skill-catalog"] })

• Capture mid-session: /kb:capture — fires proactively on KB-worthy moments (see next section). Don’t wait to be asked.
• Ship the session: /kb:push — curates whatever capture wrote (plus any hand-written changes) and opens a PR.

​

Proactive capture is on

​

When the write target is ambiguous, ask

​

Useful operational rules

• Dates: never write relative dates ("today", "EOD", "next week") into KB files. Convert to absolute YYYY-MM-DD at write time.
• Capitalisation: always DataGenie (capital G), never Datagenie or datagenie.
• CSSE: the customer-success team is CSSE, never CSSC — auto-correct on sight.
• Names not titles: reference team members by name only; team.mdx is the single source of truth for designations.
• Pipeline / health changes flow through frontmatter (stage, value, health, lastUpdated) on the prospect/account index.mdx — a timeline <Update> alone won’t move the kanban card.
• Frontmatter ↔ body must stay in sync. When you change pipeline-relevant frontmatter on a prospect/account index.mdx, in the same edit update the body’s <KeyFacts>, <PillGroup>, <StatGrid>, “Deal Summary”, “Current Status”, “Next action” callout, and append a dated row to “Deal History” — and reconcile the pipeline summary at sales/prospects/index.mdx (or customers/portfolio.mdx). See knowledge/AUTHORING.md §5.