Update to Mixpanel Headless

{
  "name": "dashboard-expert",
  "description": "Full CRUD and analysis for Mixpanel dashboards. Use when the user asks to build, create, analyze, read, understand, explain, modify, update, enhance, or manage dashboards, or asks about dashboard layout, text cards, or report arrangement. Covers dashboard analysis (read + understand existing), creation (new builds), modification (update existing), and explanation (data-driven annotation).",
  "included_files": [
    {
      "relative_path": "references/bookmark-pipeline.md",
      "size_in_bytes": 9259
    },
    {
      "relative_path": "references/chart-types.md",
      "size_in_bytes": 7517
    },
    {
      "relative_path": "references/dashboard-reference.md",
      "size_in_bytes": 38016
    },
    {
      "relative_path": "references/dashboard-templates.md",
      "size_in_bytes": 35969
    }
  ],
  "skill_md_contents": "---\nname: dashboard-expert\ndescription: >-\n  Full CRUD and analysis for Mixpanel dashboards. Use when the user asks to\n  build, create, analyze, read, understand, explain, modify, update, enhance,\n  or manage dashboards, or asks about dashboard layout, text cards, or report\n  arrangement. Covers dashboard analysis (read + understand existing), creation\n  (new builds), modification (update existing), and explanation (data-driven\n  annotation).\nallowed-tools: Bash Read Write\n---\n\n# Dashboard Expert\n\nAnalyze, build, modify, and explain Mixpanel dashboards. Four modes — pick the one matching the user's intent.\n\n## Mode Selection\n\n| User intent | Mode | Key actions |\n|---|---|---|\n| \"analyze/understand/read/explore dashboard\" | **Analyze** | Read structure, execute reports, summarize |\n| \"build/create/make a new dashboard\" | **Build** | Investigate data → plan → create with layout |\n| \"modify/update/add to/fix/improve dashboard\" | **Modify** | Read current state → plan changes → execute |\n| \"explain/annotate/add insights to dashboard\" | **Explain** | Analyze → generate data-driven text cards |\n\n## Quick Start: Analyze an Existing Dashboard\n\n```python\nimport json, re\nimport mixpanel_headless as mp\n\nws = mp.Workspace()\ndash = ws.get_dashboard(DASHBOARD_ID)\nlayout, contents = dash.layout, dash.contents\n\n# Extract structure: rows → cells → content items\nfor row_id in layout[\"order\"]:\n    row = layout[\"rows\"][row_id]\n    for cell in row[\"cells\"]:\n        cid, ctype = str(cell[\"content_id\"]), cell[\"content_type\"]\n        if ctype in (\"report\", \"report-link\"):\n            info = contents[\"report\"][cid]\n            print(f\"  [{cell['width']}w] {info['name']} ({info['type']}) {'[linked]' if ctype == 'report-link' else ''}\")\n        elif ctype == \"text\":\n            md = contents[\"text\"][cid].get(\"markdown\", \"\")\n            is_header = bool(re.search(r'<h2[\\s>]', md, re.I))\n            print(f\"  [{cell['width']}w] TEXT {'[SECTION]' if is_header else ''}: {md[:60]}...\")\n\n# Execute each report → DataFrame\nfor cid, info in contents.get(\"report\", {}).items():\n    btype, bid = info[\"type\"], info[\"id\"]\n    if btype == \"flows\":\n        result = ws.query_saved_flows(bid)\n    else:\n        result = ws.query_saved_report(bid, bookmark_type=btype)\n    df = result.df\n    print(f\"{info['name']}: {len(df)} rows, columns={list(df.columns)}\")\n```\n\n## Quick Start: Build a New Dashboard\n\n```python\nfrom mixpanel_headless.types import CreateDashboardParams, DashboardRow, DashboardRowContent\nimport json\n\nws = mp.Workspace()\ndau = ws.query(\"Login\", math=\"dau\", last=90)\n\ndef text(html):\n    return DashboardRowContent(content_type=\"text\", content_params={\"markdown\": html})\n\ndef report(name, btype, result):\n    return DashboardRowContent(content_type=\"report\", content_params={\n        \"bookmark\": {\"name\": name, \"type\": btype, \"params\": json.dumps(result.params)}})\n\ndashboard = ws.create_dashboard(CreateDashboardParams(\n    title=\"Product Health\", description=\"Core metrics.\",\n    rows=[\n        DashboardRow(contents=[text(\"<h2>Product Health</h2><p>Core metrics.</p>\")]),\n        DashboardRow(contents=[report(\"DAU (90d)\", \"insights\", dau)]),\n    ],\n))\nws.pin_dashboard(dashboard.id)  # Make visible to team\n```\n\n---\n\n## Mode: Analyze\n\nRead existing dashboards, execute their reports, and synthesize understanding.\n\n### Phase A1: Read Dashboard Structure\n\n```python\ndash = ws.get_dashboard(dashboard_id)\nlayout, contents = dash.layout, dash.contents\n```\n\nParse the response into a structured representation:\n\n- **`layout[\"order\"]`** — ordered list of row IDs\n- **`layout[\"rows\"][row_id][\"cells\"]`** — cells with `content_id`, `content_type`, `width`\n- **`contents[\"report\"][str(content_id)]`** — report metadata: `id` (bookmark_id), `name`, `type`, `params`, `description`\n- **`contents[\"text\"][str(content_id)]`** — text card: `markdown`\n\n**Classify each cell:**\n- `content_type == \"report\"` → owned, editable\n- `content_type == \"report-link\"` → linked from another dashboard, read-only\n- `content_type == \"text\"` → text card; detect section headers via `re.search(r'<h2[\\s>]', md, re.I)`\n\n**Build a mental model:** Group reports by section (text cards with `<h2>` tags delimit sections). Note each report's chart type, width, and position.\n\n### Phase A2: Extract Report Details\n\nFor deeper understanding, fetch full bookmark params:\n\n```python\nbookmark = ws.get_bookmark(bookmark_id)\nparams = bookmark.params  # Full query definition dict\n```\n\nKey fields in params (Insights format):\n- `params[\"sections\"][\"show\"]` — metrics with event names and math type\n- `params[\"sections\"][\"group\"]` — breakdown properties\n- `params[\"sections\"][\"filter\"]` — active filters\n- `params[\"sections\"][\"time\"]` — date range\n- `params[\"displayOptions\"][\"chartType\"]` — visualization type\n\nNote: `params` in `contents[\"report\"][id]` may be a JSON string — parse with `json.loads()` if needed.\n\n### Phase A3: Execute and Summarize\n\nExecute each report to get live data:\n\n```python\nfor cid, info in contents.get(\"report\", {}).items():\n    bid, btype = info[\"id\"], info[\"type\"]\n    if btype == \"flows\":\n        result = ws.query_saved_flows(bid)\n    else:\n        result = ws.query_saved_report(bid, bookmark_type=btype)\n    df = result.df\n```\n\n**Summarize by report type:**\n\n| Type | Key metrics to extract |\n|---|---|\n| insights | Total, average, latest value, min, max, trend direction |\n| funnels | Step names, counts, per-step and overall conversion rate |\n| retention | Day 1, Day 7, Day 30 rates; stabilization point |\n| flows | Top paths, conversion rate, drop-off points |\n\n**Cross-correlate across reports:** Look for relationships — DAU trends vs. retention, funnel drop-off vs. feature adoption.\n\n### Phase A4: Present Analysis\n\nStructure findings as:\n1. **Dashboard overview** — title, purpose, section count, report count\n2. **Section-by-section breakdown** — what each section measures, key findings\n3. **Cross-metric insights** — correlations, anomalies, patterns\n4. **Suggestions** — missing metrics, better chart types, layout improvements\n\n### Multi-Dashboard Analysis\n\nWhen analyzing multiple dashboards, build a unified picture:\n\n```python\ndashboard_ids = [1001, 1002, 1003]\nall_data = {}\nfor did in dashboard_ids:\n    dash = ws.get_dashboard(did)\n    for cid, info in dash.contents.get(\"report\", {}).items():\n        result = ws.query_saved_report(info[\"id\"], bookmark_type=info[\"type\"])\n        all_data[f\"{dash.title}/{info['name']}\"] = result.df\n# Cross-dashboard: join DataFrames on date index, compute correlations\n```\n\n---\n\n## Mode: Build\n\nCreate new dashboards from scratch. Five phases.\n\n### Phase B1: Investigate\n\nBefore building, discover the data. Never build reports for events with zero volume.\n\n```python\nws = mp.Workspace()\ntop = ws.top_events(limit=15)\nfor t in top:\n    print(f\"{t.event}: {t.count:,} ({t.percent_change:+.1%})\")\n\n# Validate candidate events\nfor event in candidate_events:\n    result = ws.query(event, from_date=\"2025-01-01\", to_date=\"2025-03-31\")\n    print(f\"{event}: {result.df['count'].sum():,.0f} total\")\n\n# Explore properties for breakdowns\nprops = ws.properties(event=\"key_event\")\nvalues = ws.property_values(event=\"key_event\", property=\"platform\", limit=20)\n```\n\n### Phase B2: Plan Structure\n\nPresent a proposed structure before building. Choose a template from `references/dashboard-templates.md`.\n\n**A plan includes:** title + description, sections with text card headers, reports per section with chart type, grid layout.\n\n**Text cards use HTML** (not markdown). Every dashboard must have an intro text card and section headers.\n\n**Allowed HTML tags:** `<h1>`, `<h2>`, `<h3>`, `<p>`, `<strong>`, `<em>`, `<u>`, `<s>`, `<mark>`, `<code>`, `<blockquote>`, `<hr>`, `<br>`, `<ul>`, `<ol>`, `<li>`, `<a href=\"...\">`\n\n**Forbidden (stripped):** `<div>`, `<span>`, `<b>` (use `<strong>`), `<i>` (use `<em>`), `<img>`, `<table>`\n\n**Critical:** Strip `\\n` and collapse whitespace from HTML before sending. Each element renders as its own line.\n\n**Text card patterns:**\n```\nIntro:     <h2>Dashboard Title</h2><p>What and why. Time period: last 90 days.</p>\nSection:   <h2>Acquisition</h2><p>How users discover and sign up.</p>\nExplainer: <p>^ Signup conversion is <strong>23.4%</strong>, up 2.1pp.</p>\n```\n\n### Phase B3: Query and Build\n\nQuery each metric, verify data, then create with layout in one call.\n\n```python\ndef text(html):\n    return DashboardRowContent(content_type=\"text\", content_params={\"markdown\": html})\n\ndef report(name, btype, result, description=None):\n    params = {\"bookmark\": {\"name\": name, \"type\": btype, \"params\": json.dumps(result.params)}}\n    if description:\n        params[\"bookmark\"][\"description\"] = description\n    return DashboardRowContent(content_type=\"report\", content_params=params)\n\ndashboard = ws.create_dashboard(CreateDashboardParams(\n    title=\"Product Health Dashboard\",\n    description=\"Key metrics for product health monitoring.\",\n    rows=[\n        DashboardRow(contents=[text(\"<h2>Product Health</h2><p>Updated daily.</p>\")]),\n        DashboardRow(contents=[\n            report(\"DAU (90d)\", \"insights\", dau),\n            report(\"Signups (90d)\", \"insights\", signups),\n            report(\"Revenue (90d)\", \"insights\", revenue),\n        ]),\n        DashboardRow(contents=[text(\"<h2>Conversion</h2><p>Key funnels.</p>\")]),\n        DashboardRow(contents=[report(\"Signup Funnel\", \"funnels\", funnel)]),\n    ],\n))\n```\n\n**On report failure**, substitute a fallback text card:\n```python\ntry:\n    result = ws.query(event, math=\"total\", last=90)\n    row_items.append(report(f\"{event} Trend\", \"insights\", result))\nexcept Exception as e:\n    row_items.append(text(f\"<p><strong>Failed:</strong> {event} — {e}</p>\"))\n```\n\n### Phase B4: Enhance\n\n- **Pin for team visibility:** `ws.pin_dashboard(dashboard.id)` — dashboards are invisible by default\n- **Favorite for personal use:** `ws.favorite_dashboard(dashboard.id)`\n- **Add explainer cards:** see Mode: Explain\n- **Adjust heights:** see `references/dashboard-reference.md` Section 3.4\n\n### Phase B5: Verify\n\nOpen the dashboard and confirm all reports render with data, text cards display correctly, and layout matches the plan.\n\n---\n\n## Mode: Modify\n\nUpdate existing dashboards. Read first, then apply changes in the correct order.\n\n### Phase M1: Read Current State\n\nUse Analyze Phase A1-A2 to understand the dashboard's structure. Present to user before making changes.\n\n### Phase M2: Plan Changes\n\nClassify each change and plan execution order. Operations **must** follow this sequence:\n\n1. **Metadata** (title/description) — standalone PATCH\n2. **Cell creates** — add new content first\n3. **Row reorder** (`rows_order`) — after creates so temp IDs resolve\n4. **Cell updates** — modify existing content\n5. **Cell deletes** — remove content\n6. **Row deletes** — remove entire rows last\n\n### Phase M3: Execute Changes\n\n**Adding content to a specific existing row** — send `content` AND `layout` together:\n\n```python\nimport copy\ndash = ws.get_dashboard(dashboard_id)\nlayout = copy.deepcopy(dash.layout)\ntarget_row = layout[\"rows\"][target_row_id]\n\n# Redistribute widths\nnew_count = len(target_row[\"cells\"]) + 1\ncell_width = 12 // new_count\nfor cell in target_row[\"cells\"]:\n    cell[\"width\"] = cell_width\ntarget_row[\"cells\"].append({\"temp_id\": \"-1\", \"width\": cell_width})\n\nws.update_dashboard(dashboard_id, UpdateDashboardParams(\n    content={\"action\": \"create\", \"content_type\": \"report\",\n             \"content_params\": {\"bookmark\": {\"name\": \"New Report\", \"type\": \"insights\",\n                                              \"params\": json.dumps(result.params)}}},\n    layout={\"rows_order\": layout[\"order\"], \"rows\": layout[\"rows\"]},\n))\n```\n\n**Adding content as a new row** — content action alone (appends to bottom):\n\n```python\nws.update_dashboard(dashboard_id, UpdateDashboardParams(\n    content={\"action\": \"create\", \"content_type\": \"text\",\n             \"content_params\": {\"markdown\": \"<p>^ Explainer card.</p>\"}},\n))\n```\n\n**Deleting content:**\n\n```python\nws.update_dashboard(dashboard_id, UpdateDashboardParams(\n    content={\"action\": \"delete\", \"content_type\": \"report\", \"content_id\": content_id},\n))\n```\n\n**Cross-type updates** (e.g., text → report): API rejects changing `content_type` on update. Delete the old cell, then create the new one.\n\nSee `references/dashboard-reference.md` Section 8 for temp ID resolution, operation ordering details, and report-link semantics.\n\n---\n\n## Mode: Explain\n\nCombine analysis with targeted text card insertion.\n\n1. **Analyze** — run Mode: Analyze to extract structure and execute reports\n2. **Generate insights** — for each report, compute key metrics from the DataFrame:\n   ```python\n   latest = df.iloc[-1][\"count\"]\n   prev = df.iloc[-8][\"count\"]\n   trend = ((latest - prev) / prev) * 100\n   html = (f\"<p>^ DAU is <strong>{latest:,.0f}</strong>, \"\n           f\"{'up' if trend > 0 else 'down'} <strong>{abs(trend):.1f}%</strong> \"\n           f\"vs. last week.</p>\").replace(\"\\n\", \"\")\n   ```\n3. **Insert cards** — add as new rows below each report section:\n   ```python\n   ws.update_dashboard(dashboard_id, UpdateDashboardParams(\n       content={\"action\": \"create\", \"content_type\": \"text\",\n                \"content_params\": {\"markdown\": html}},\n   ))\n   ```\n\n---\n\n## Critical Gotchas\n\n1. **Combined content+layout PATCH** — send both `content` and `layout` in the same `UpdateDashboardParams` to add cells to specific existing rows. Without `layout`, new content appends as a full-width row at the bottom.\n\n2. **Width auto-redistribution** — when adding to an existing row with N cells, set all cells (including new) to `12 // (N+1)` width.\n\n3. **Update operation ordering** — metadata → cell creates → rows_order → cell updates → cell deletes → row deletes. Wrong order causes failures.\n\n4. **`per_user` requires `math_property`** — using per-user aggregation without a numeric property raises `BookmarkValidationError`.\n\n5. **`CreateBookmarkParams(dashboard_id=X)` does NOT add to layout** — use `add_report_to_dashboard()` or inline content action.\n\n6. **`add_report_to_dashboard()` CLONES** — creates \"Duplicate of...\" copy. Use `rows` in `CreateDashboardParams` or inline content action instead.\n\n7. **GET `order` vs PATCH `rows_order`** — layout from GET uses `order`; PATCH expects `rows_order`.\n\n8. **Never include `version` in layout PATCH** — the API rejects it.\n\n9. **Strip `\\n` and collapse whitespace** — call `.replace(\"\\n\", \"\").strip()` on text card HTML. Newlines cause TipTap to mangle content.\n\n10. **Limits** — title 255 chars, description 400 chars, text cards 2,000 chars, max 4 items/row, max 30 rows.\n\n11. **Cross-type cell updates require delete+create** — API rejects changing `content_type` on an update action.\n\n12. **Report-link cells are read-only** — `content_type: \"report-link\"` references a report owned by another dashboard. You can view but not edit its params.\n\n13. **Auto-pin after creation** — dashboards are invisible to the team by default. Call `ws.pin_dashboard(dashboard.id)`.\n\n14. **The `markdown` field accepts only HTML** — despite the name. Markdown syntax renders as literal text.\n\n## See Also\n\n- `references/dashboard-reference.md` — Complete API reference, layout system, content actions, text card formatting, update operations, analysis patterns\n- `references/dashboard-templates.md` — 9 purpose-built dashboard templates with section layouts and report specs\n- `references/bookmark-pipeline.md` — End-to-end pipeline from typed query to dashboard report for all 4 engines\n- `references/chart-types.md` — Chart type selection guide with slugs, use cases, and width recommendations\n"
}