@hailer/mcp 0.0.1

package/.claude/skills/create-insight-skill/SKILL.md

@@ -0,0 +1,1317 @@
+---
+name: Creating Hailer Insights
+description: Complete guide for creating SQL-like insights over Hailer workflow data - use when building reports, analytics, or data queries
+---
+
+# Creating Hailer Insights - Complete Guide
+
+Complete reference for creating SQL-like insights that query Hailer workflow data using the `create_insight` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Core Concepts](#core-concepts)
+4. [Meta Fields Reference](#meta-fields-reference)
+5. [Basic Examples](#basic-examples)
+6. [SQL Features](#sql-features)
+7. [Advanced Queries](#advanced-queries)
+8. [Joins and Relationships](#joins-and-relationships)
+9. [Aggregations and Grouping](#aggregations-and-grouping)
+10. [Best Practices](#best-practices)
+11. [Common Patterns](#common-patterns)
+12. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**Simple Report (Single Workflow):**
+
+```javascript
+create_insight({
+  name: 'All Tasks Report',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'dueDate', fieldId: 'due-date-field-id' }
+    ]
+  }],
+  query: 'SELECT title, dueDate FROM tasks WHERE dueDate > "2024-01-01"'
+})
+```
+
+**Cross-Workflow Join:**
+
+```javascript
+create_insight({
+  name: 'Tasks with Projects',
+  sources: [
+    {
+      name: 'tasks',
+      workflowId: 'tasks-workflow-id',
+      fields: [
+        { name: 'taskName', meta: 'name' },
+        { name: 'projectLink', fieldId: 'project-field-id' }
+      ]
+    },
+    {
+      name: 'projects',
+      workflowId: 'projects-workflow-id',
+      fields: [
+        { name: 'id', meta: '_id' },
+        { name: 'projectName', meta: 'name' }
+      ]
+    }
+  ],
+  query: `
+    SELECT tasks.taskName, projects.projectName
+    FROM tasks
+    LEFT JOIN projects ON tasks.projectLink = projects.id
+  `
+})
+```
+
+**Key Concepts:**
+- Workflows = Database tables
+- Activities = Rows
+- Fields = Columns
+- Insights = SELECT queries with JOINs
+- Meta fields = Built-in activity properties
+
+## Overview
+
+**What are Insights?**
+
+Insights are SQL queries that run over your Hailer workflow data. They enable powerful reporting and analytics capabilities without writing custom code.
+
+**Think of it as:**
+- SQL SELECT queries on workflow data
+- Virtual database views over Hailer
+- Reports that update in real-time
+- Cross-workflow analytics
+
+**Common Uses:**
+- Generate reports (tasks by status, projects by team)
+- Analyze trends (activities created per month)
+- Track metrics (completion rates, time to close)
+- Cross-workflow summaries (tasks per project)
+- Data exports for external tools
+
+**Key Features:**
+- Full SQL syntax support
+- Cross-workflow JOINs
+- Aggregations (COUNT, SUM, AVG, MIN, MAX)
+- Filtering with WHERE clauses
+- Sorting with ORDER BY
+- Public/private access control
+
+## Core Concepts
+
+### Sources
+
+**Sources define which workflows to query:**
+
+```javascript
+sources: [{
+  name: 'tasks',           // SQL table alias
+  workflowId: 'wf-id',     // Which workflow to query
+  fields: [                 // Field mappings
+    { name: 'title', meta: 'name' },
+    { name: 'priority', fieldId: 'field-id' }
+  ]
+}]
+```
+
+**Think of sources as:**
+- Table definitions in SQL
+- Each source = one workflow
+- Fields = column mappings
+- Name = table alias for queries
+
+### Field Mappings
+
+**Two types of field mappings:**
+
+**1. Meta Fields (Built-in):**
+```javascript
+{ name: 'title', meta: 'name' }        // Activity name
+{ name: 'id', meta: '_id' }            // Activity ID
+{ name: 'created', meta: 'created' }   // Creation date
+```
+
+**2. Custom Fields:**
+```javascript
+{ name: 'priority', fieldId: 'field-id' }  // Custom field
+{ name: 'dueDate', fieldId: 'field-id' }   // Custom field
+```
+
+### Workflow → SQL Mapping
+
+| Hailer Concept | SQL Concept | Example |
+|----------------|-------------|---------|
+| Workflow | Table | `tasks` table |
+| Activity | Row | One task row |
+| Field | Column | `priority` column |
+| ActivityLink | Foreign Key | JOIN on `project_id` |
+| Insight | SELECT Query | Report query |
+
+## Meta Fields Reference
+
+**Built-in activity properties available in all workflows:**
+
+### Available Meta Fields
+
+| Meta Field | Type | Description | Usage |
+|------------|------|-------------|-------|
+| `_id` | string | Activity ID | For JOINs |
+| `uid` | string | User ID (creator) | User filtering |
+| `team` | string | Owner team ID | Team filtering |
+| `createdBy` | string | Creator user ID | Track who created |
+| `name` | string | Activity name/title | Display name |
+| `created` | timestamp | Creation date/time | Sorting, filtering |
+| `updated` | timestamp | Last update date/time | Recent changes |
+| `phaseId` | string | Current phase ID | Status/phase grouping |
+| `phaseName` | string | Current phase name | Display phase name |
+| `phaseLastMove` | timestamp | Last phase change | Track phase transitions |
+| `workflowId` | string | Workflow ID | Identify source workflow |
+| `workflowName` | string | Workflow name | Display workflow name |
+| `priority` | number | Activity priority | Priority filtering |
+
+### Meta Field Examples
+
+**Activity Name:**
+```javascript
+{ name: 'title', meta: 'name' }
+// Query: SELECT title FROM tasks
+```
+
+**Activity ID (for JOINs):**
+```javascript
+{ name: 'id', meta: '_id' }
+// Query: SELECT id FROM tasks
+// JOIN: ON tasks.projectId = projects.id
+```
+
+**Created Date:**
+```javascript
+{ name: 'createdDate', meta: 'created' }
+// Query: SELECT createdDate FROM tasks WHERE createdDate > '2024-01-01'
+```
+
+**Updated Date:**
+```javascript
+{ name: 'lastUpdated', meta: 'updated' }
+// Query: SELECT lastUpdated FROM tasks ORDER BY lastUpdated DESC
+```
+
+**Phase ID (Status):**
+```javascript
+{ name: 'status', meta: 'phaseId' }
+// Query: SELECT status FROM tasks GROUP BY status
+```
+
+**Phase Name (Readable Status):**
+```javascript
+{ name: 'statusName', meta: 'phaseName' }
+// Query: SELECT statusName FROM tasks
+```
+
+**Team:**
+```javascript
+{ name: 'ownerTeam', meta: 'team' }
+// Query: SELECT ownerTeam FROM tasks WHERE ownerTeam = 'team-id'
+```
+
+## Basic Examples
+
+### Example 1: Simple List Query
+
+**Goal:** List all tasks with due dates.
+
+```javascript
+create_insight({
+  name: 'Tasks with Due Dates',
+  sources: [{
+    name: 'tasks',
+    workflowId: '68446dc05b30685f67c6fcd4',
+    fields: [
+      { name: 'taskName', meta: 'name' },
+      { name: 'dueDate', fieldId: 'due-date-field-id' },
+      { name: 'priority', fieldId: 'priority-field-id' }
+    ]
+  }],
+  query: 'SELECT taskName, dueDate, priority FROM tasks'
+})
+```
+
+### Example 2: Filtered Query
+
+**Goal:** Show only high-priority tasks due this month.
+
+```javascript
+create_insight({
+  name: 'High Priority Tasks Due Soon',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'dueDate', fieldId: 'due-date-field-id' },
+      { name: 'priority', fieldId: 'priority-field-id' }
+    ]
+  }],
+  query: `
+    SELECT title, dueDate, priority
+    FROM tasks
+    WHERE priority = 'High'
+      AND dueDate >= '2024-12-01'
+      AND dueDate <= '2024-12-31'
+  `
+})
+```
+
+### Example 3: Sorted Query
+
+**Goal:** Recent tasks, newest first.
+
+```javascript
+create_insight({
+  name: 'Recently Created Tasks',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'created', meta: 'created' }
+    ]
+  }],
+  query: `
+    SELECT title, created
+    FROM tasks
+    ORDER BY created DESC
+    LIMIT 50
+  `
+})
+```
+
+### Example 4: Public Insight
+
+**Goal:** Shareable report accessible without authentication.
+
+```javascript
+create_insight({
+  name: 'Project Status Dashboard',
+  public: true,  // Publicly accessible
+  sources: [{
+    name: 'projects',
+    workflowId: 'projects-workflow-id',
+    fields: [
+      { name: 'projectName', meta: 'name' },
+      { name: 'status', fieldId: 'status-field-id' },
+      { name: 'budget', fieldId: 'budget-field-id' }
+    ]
+  }],
+  query: 'SELECT projectName, status, budget FROM projects'
+})
+```
+
+## SQL Features
+
+### SELECT Statement
+
+**Basic SELECT:**
+```sql
+SELECT title, priority FROM tasks
+```
+
+**SELECT with aliases:**
+```sql
+SELECT
+  title AS "Task Name",
+  priority AS "Priority Level"
+FROM tasks
+```
+
+**SELECT all columns:**
+```sql
+SELECT * FROM tasks
+```
+
+**SELECT distinct values:**
+```sql
+SELECT DISTINCT priority FROM tasks
+```
+
+### WHERE Clause
+
+**Comparison operators:**
+```sql
+WHERE priority = 'High'                    -- Equal
+WHERE dueDate > '2024-01-01'              -- Greater than
+WHERE quantity < 100                       -- Less than
+WHERE status != 'Done'                     -- Not equal
+WHERE price >= 50                          -- Greater than or equal
+WHERE count <= 10                          -- Less than or equal
+```
+
+**Logical operators:**
+```sql
+WHERE priority = 'High' AND status = 'Open'           -- AND
+WHERE priority = 'High' OR priority = 'Urgent'        -- OR
+WHERE NOT status = 'Done'                             -- NOT
+```
+
+**Pattern matching:**
+```sql
+WHERE title LIKE '%report%'                -- Contains
+WHERE email LIKE 'admin@%'                 -- Starts with
+WHERE name LIKE '%Smith'                   -- Ends with
+```
+
+**NULL checks:**
+```sql
+WHERE dueDate IS NULL                      -- No due date
+WHERE assignee IS NOT NULL                 -- Has assignee
+```
+
+**IN operator:**
+```sql
+WHERE priority IN ('High', 'Urgent')
+WHERE status IN ('Open', 'In Progress')
+```
+
+**BETWEEN operator:**
+```sql
+WHERE dueDate BETWEEN '2024-01-01' AND '2024-12-31'
+WHERE quantity BETWEEN 10 AND 100
+```
+
+### ORDER BY Clause
+
+**Sort ascending:**
+```sql
+ORDER BY dueDate ASC
+ORDER BY priority
+```
+
+**Sort descending:**
+```sql
+ORDER BY created DESC
+ORDER BY quantity DESC
+```
+
+**Multiple columns:**
+```sql
+ORDER BY priority DESC, dueDate ASC
+```
+
+### LIMIT and OFFSET
+
+**Limit results:**
+```sql
+SELECT * FROM tasks LIMIT 10
+```
+
+**Pagination:**
+```sql
+SELECT * FROM tasks LIMIT 10 OFFSET 20    -- Skip 20, take 10
+```
+
+## Advanced Queries
+
+### Complex Filtering
+
+**Multiple conditions:**
+```javascript
+create_insight({
+  name: 'Complex Task Filter',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'priority', fieldId: 'priority-field-id' },
+      { name: 'status', fieldId: 'status-field-id' },
+      { name: 'dueDate', fieldId: 'due-date-field-id' }
+    ]
+  }],
+  query: `
+    SELECT title, priority, status, dueDate
+    FROM tasks
+    WHERE (priority = 'High' OR priority = 'Urgent')
+      AND status != 'Done'
+      AND (dueDate < '2024-12-31' OR dueDate IS NULL)
+    ORDER BY priority DESC, dueDate ASC
+  `
+})
+```
+
+### Calculated Columns
+
+**String concatenation:**
+```sql
+SELECT
+  title || ' - ' || priority AS "Full Description"
+FROM tasks
+```
+
+**Date calculations:**
+```sql
+SELECT
+  title,
+  dueDate,
+  JULIANDAY(dueDate) - JULIANDAY('now') AS "Days Until Due"
+FROM tasks
+WHERE dueDate > date('now')
+```
+
+### Subqueries
+
+**Filter by subquery result:**
+```sql
+SELECT title, projectId
+FROM tasks
+WHERE projectId IN (
+  SELECT id
+  FROM projects
+  WHERE status = 'Active'
+)
+```
+
+## Joins and Relationships
+
+### INNER JOIN
+
+**Only matching records:**
+
+```javascript
+create_insight({
+  name: 'Tasks with Projects (Must Have Project)',
+  sources: [
+    {
+      name: 'tasks',
+      workflowId: 'tasks-workflow-id',
+      fields: [
+        { name: 'taskName', meta: 'name' },
+        { name: 'projectLink', fieldId: 'project-link-field-id' }
+      ]
+    },
+    {
+      name: 'projects',
+      workflowId: 'projects-workflow-id',
+      fields: [
+        { name: 'id', meta: '_id' },
+        { name: 'projectName', meta: 'name' }
+      ]
+    }
+  ],
+  query: `
+    SELECT tasks.taskName, projects.projectName
+    FROM tasks
+    INNER JOIN projects ON tasks.projectLink = projects.id
+  `
+})
+```
+
+### LEFT JOIN
+
+**All left records + matching right records:**
+
+```javascript
+create_insight({
+  name: 'All Tasks with Optional Projects',
+  sources: [
+    {
+      name: 'tasks',
+      workflowId: 'tasks-workflow-id',
+      fields: [
+        { name: 'taskName', meta: 'name' },
+        { name: 'projectLink', fieldId: 'project-link-field-id' }
+      ]
+    },
+    {
+      name: 'projects',
+      workflowId: 'projects-workflow-id',
+      fields: [
+        { name: 'id', meta: '_id' },
+        { name: 'projectName', meta: 'name' }
+      ]
+    }
+  ],
+  query: `
+    SELECT
+      tasks.taskName,
+      COALESCE(projects.projectName, 'No Project') AS projectName
+    FROM tasks
+    LEFT JOIN projects ON tasks.projectLink = projects.id
+  `
+})
+```
+
+### Multiple Joins
+
+**Three-level hierarchy:**
+
+```javascript
+create_insight({
+  name: 'Tasks → Topics → Projects',
+  sources: [
+    {
+      name: 'tasks',
+      workflowId: 'tasks-workflow-id',
+      fields: [
+        { name: 'taskName', meta: 'name' },
+        { name: 'topicLink', fieldId: 'topic-field-id' }
+      ]
+    },
+    {
+      name: 'topics',
+      workflowId: 'topics-workflow-id',
+      fields: [
+        { name: 'id', meta: '_id' },
+        { name: 'topicName', meta: 'name' },
+        { name: 'projectLink', fieldId: 'project-field-id' }
+      ]
+    },
+    {
+      name: 'projects',
+      workflowId: 'projects-workflow-id',
+      fields: [
+        { name: 'id', meta: '_id' },
+        { name: 'projectName', meta: 'name' }
+      ]
+    }
+  ],
+  query: `
+    SELECT
+      tasks.taskName,
+      topics.topicName,
+      projects.projectName
+    FROM tasks
+    LEFT JOIN topics ON tasks.topicLink = topics.id
+    LEFT JOIN projects ON topics.projectLink = projects.id
+  `
+})
+```
+
+## Aggregations and Grouping
+
+### COUNT
+
+**Count all activities:**
+```javascript
+create_insight({
+  name: 'Total Task Count',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'id', meta: '_id' }
+    ]
+  }],
+  query: 'SELECT COUNT(*) AS total FROM tasks'
+})
+```
+
+**Count by group:**
+```javascript
+create_insight({
+  name: 'Tasks by Priority',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'priority', fieldId: 'priority-field-id' }
+    ]
+  }],
+  query: `
+    SELECT priority, COUNT(*) AS count
+    FROM tasks
+    GROUP BY priority
+    ORDER BY count DESC
+  `
+})
+```
+
+### SUM
+
+**Sum numeric values:**
+```javascript
+create_insight({
+  name: 'Total Project Budget',
+  sources: [{
+    name: 'projects',
+    workflowId: 'projects-workflow-id',
+    fields: [
+      { name: 'budget', fieldId: 'budget-field-id' }
+    ]
+  }],
+  query: 'SELECT SUM(budget) AS totalBudget FROM projects'
+})
+```
+
+**Sum by group:**
+```javascript
+create_insight({
+  name: 'Budget by Status',
+  sources: [{
+    name: 'projects',
+    workflowId: 'projects-workflow-id',
+    fields: [
+      { name: 'status', fieldId: 'status-field-id' },
+      { name: 'budget', fieldId: 'budget-field-id' }
+    ]
+  }],
+  query: `
+    SELECT status, SUM(budget) AS totalBudget
+    FROM projects
+    GROUP BY status
+  `
+})
+```
+
+### AVG, MIN, MAX
+
+**Statistical aggregations:**
+```javascript
+create_insight({
+  name: 'Project Budget Statistics',
+  sources: [{
+    name: 'projects',
+    workflowId: 'projects-workflow-id',
+    fields: [
+      { name: 'budget', fieldId: 'budget-field-id' }
+    ]
+  }],
+  query: `
+    SELECT
+      AVG(budget) AS avgBudget,
+      MIN(budget) AS minBudget,
+      MAX(budget) AS maxBudget,
+      COUNT(*) AS projectCount
+    FROM projects
+  `
+})
+```
+
+### HAVING Clause
+
+**Filter aggregated results:**
+```javascript
+create_insight({
+  name: 'Priorities with 5+ Tasks',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'priority', fieldId: 'priority-field-id' }
+    ]
+  }],
+  query: `
+    SELECT priority, COUNT(*) AS taskCount
+    FROM tasks
+    GROUP BY priority
+    HAVING COUNT(*) >= 5
+    ORDER BY taskCount DESC
+  `
+})
+```
+
+## Best Practices
+
+### 1. Test with preview_insight First
+
+**Always test queries before creating:**
+
+```javascript
+// 1. Test with preview
+preview_insight({
+  sources: [...],
+  query: 'SELECT ...'
+})
+
+// 2. If successful, create insight
+create_insight({
+  name: 'My Insight',
+  sources: [...],
+  query: 'SELECT ...'
+})
+```
+
+### 2. Use Descriptive Source Names
+
+**Bad:**
+```javascript
+sources: [
+  { name: 't1', workflowId: '...' },
+  { name: 't2', workflowId: '...' }
+]
+```
+
+**Good:**
+```javascript
+sources: [
+  { name: 'tasks', workflowId: '...' },
+  { name: 'projects', workflowId: '...' }
+]
+```
+
+### 3. Use Descriptive Column Names
+
+**Bad:**
+```sql
+SELECT t.a, p.b FROM tasks t JOIN projects p ON t.c = p.d
+```
+
+**Good:**
+```sql
+SELECT
+  tasks.taskName AS "Task Name",
+  projects.projectName AS "Project Name"
+FROM tasks
+LEFT JOIN projects ON tasks.projectId = projects.id
+```
+
+### 4. Include id Field for JOINs
+
+**Always include _id in sources used for joins:**
+
+```javascript
+sources: [
+  {
+    name: 'projects',
+    workflowId: 'projects-workflow-id',
+    fields: [
+      { name: 'id', meta: '_id' },      // Required for JOINs
+      { name: 'projectName', meta: 'name' }
+    ]
+  }
+]
+```
+
+### 5. Use LEFT JOIN for Optional Relationships
+
+```javascript
+// Good: Shows all tasks, even without projects
+LEFT JOIN projects ON tasks.projectId = projects.id
+
+// Bad: Only shows tasks with projects
+INNER JOIN projects ON tasks.projectId = projects.id
+```
+
+### 6. Get Field IDs from get_workflow_schema
+
+```javascript
+// 1. Get schema
+const schema = get_workflow_schema({
+  workflowId: 'workflow-id'
+})
+
+// 2. Find field IDs
+const priorityField = schema.fields.find(f => f.key === 'priority')
+console.log('Priority field ID:', priorityField._id)
+
+// 3. Use in insight
+create_insight({
+  sources: [{
+    fields: [
+      { name: 'priority', fieldId: priorityField._id }
+    ]
+  }],
+  query: '...'
+})
+```
+
+### 7. Handle NULL Values
+
+**Use COALESCE for defaults:**
+```sql
+SELECT
+  taskName,
+  COALESCE(priority, 'Not Set') AS priority
+FROM tasks
+```
+
+**Check for NULL explicitly:**
+```sql
+SELECT taskName
+FROM tasks
+WHERE dueDate IS NOT NULL
+```
+
+### 8. Limit Large Result Sets
+
+```sql
+-- Good: Limit results
+SELECT * FROM tasks ORDER BY created DESC LIMIT 100
+
+-- Bad: Could return thousands of rows
+SELECT * FROM tasks
+```
+
+### 9. Use Meaningful Insight Names
+
+**Bad:**
+- "Report 1"
+- "Query"
+- "Test"
+
+**Good:**
+- "High Priority Tasks Due This Month"
+- "Projects by Team and Budget"
+- "Task Completion Rate by Priority"
+
+### 10. Document Complex Queries
+
+```javascript
+create_insight({
+  name: 'Task Status Report',
+  sources: [...],
+  query: `
+    -- Show all tasks with their project and priority
+    -- Excludes tasks in 'Done' status
+    -- Sorted by priority (High first) and due date
+    SELECT
+      tasks.taskName,
+      projects.projectName,
+      tasks.priority,
+      tasks.dueDate
+    FROM tasks
+    LEFT JOIN projects ON tasks.projectId = projects.id
+    WHERE tasks.status != 'Done'
+    ORDER BY
+      CASE tasks.priority
+        WHEN 'Urgent' THEN 1
+        WHEN 'High' THEN 2
+        WHEN 'Medium' THEN 3
+        ELSE 4
+      END,
+      tasks.dueDate ASC
+  `
+})
+```
+
+## Common Patterns
+
+### Pattern 1: Recent Activities Report
+
+```javascript
+create_insight({
+  name: 'Recently Created Tasks',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'created', meta: 'created' },
+      { name: 'priority', fieldId: 'priority-field-id' }
+    ]
+  }],
+  query: `
+    SELECT title, created, priority
+    FROM tasks
+    WHERE created >= date('now', '-7 days')
+    ORDER BY created DESC
+  `
+})
+```
+
+### Pattern 2: Status Distribution
+
+```javascript
+create_insight({
+  name: 'Task Status Distribution',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'status', meta: 'phase' }
+    ]
+  }],
+  query: `
+    SELECT
+      status,
+      COUNT(*) AS count,
+      ROUND(COUNT(*) * 100.0 / (SELECT COUNT(*) FROM tasks), 2) AS percentage
+    FROM tasks
+    GROUP BY status
+    ORDER BY count DESC
+  `
+})
+```
+
+### Pattern 3: Overdue Tasks
+
+```javascript
+create_insight({
+  name: 'Overdue Tasks',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'dueDate', fieldId: 'due-date-field-id' },
+      { name: 'priority', fieldId: 'priority-field-id' }
+    ]
+  }],
+  query: `
+    SELECT title, dueDate, priority
+    FROM tasks
+    WHERE dueDate < date('now')
+      AND status != 'Done'
+    ORDER BY dueDate ASC
+  `
+})
+```
+
+### Pattern 4: Monthly Trends
+
+```javascript
+create_insight({
+  name: 'Tasks Created Per Month',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'created', meta: 'created' }
+    ]
+  }],
+  query: `
+    SELECT
+      strftime('%Y-%m', created) AS month,
+      COUNT(*) AS taskCount
+    FROM tasks
+    GROUP BY month
+    ORDER BY month DESC
+  `
+})
+```
+
+### Pattern 5: Top N Report
+
+```javascript
+create_insight({
+  name: 'Top 10 Projects by Task Count',
+  sources: [
+    {
+      name: 'tasks',
+      workflowId: 'tasks-workflow-id',
+      fields: [
+        { name: 'projectId', fieldId: 'project-field-id' }
+      ]
+    },
+    {
+      name: 'projects',
+      workflowId: 'projects-workflow-id',
+      fields: [
+        { name: 'id', meta: '_id' },
+        { name: 'projectName', meta: 'name' }
+      ]
+    }
+  ],
+  query: `
+    SELECT
+      projects.projectName,
+      COUNT(tasks.projectId) AS taskCount
+    FROM projects
+    LEFT JOIN tasks ON projects.id = tasks.projectId
+    GROUP BY projects.id, projects.projectName
+    ORDER BY taskCount DESC
+    LIMIT 10
+  `
+})
+```
+
+### Pattern 6: Missing Data Report
+
+```javascript
+create_insight({
+  name: 'Tasks Without Due Date',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'dueDate', fieldId: 'due-date-field-id' },
+      { name: 'created', meta: 'created' }
+    ]
+  }],
+  query: `
+    SELECT title, created
+    FROM tasks
+    WHERE dueDate IS NULL
+    ORDER BY created DESC
+  `
+})
+```
+
+## Troubleshooting
+
+### Error: "SQL Query Error"
+
+**Cause:** Invalid SQL syntax.
+
+**Solutions:**
+
+1. **Test with preview_insight first:**
+```javascript
+preview_insight({
+  sources: [...],
+  query: 'SELECT ...'
+})
+```
+
+2. **Check common syntax errors:**
+```sql
+-- Missing FROM clause
+SELECT title             -- ❌ Missing FROM
+SELECT title FROM tasks  -- ✅ Correct
+
+-- Invalid column name
+SELECT titleee FROM tasks           -- ❌ Typo
+SELECT title FROM tasks            -- ✅ Correct
+
+-- Missing quotes around strings
+WHERE priority = High               -- ❌ No quotes
+WHERE priority = 'High'            -- ✅ Quoted
+
+-- Unmatched parentheses
+WHERE (priority = 'High'           -- ❌ Missing )
+WHERE (priority = 'High')          -- ✅ Matched
+```
+
+3. **Verify field names match source definitions:**
+```javascript
+sources: [{
+  fields: [
+    { name: 'priority', fieldId: '...' }  // Name must match query
+  ]
+}],
+query: 'SELECT priority FROM tasks'      // Must use 'priority'
+```
+
+### Error: "Invalid field IDs or workflow IDs"
+
+**Cause:** Field IDs don't exist in workflow.
+
+**Solution:**
+
+```javascript
+// 1. Get correct field IDs
+const schema = get_workflow_schema({
+  workflowId: 'workflow-id'
+})
+
+// 2. Find field
+const field = schema.fields.find(f => f.key === 'priority')
+console.log('Field ID:', field._id)
+
+// 3. Use correct ID
+create_insight({
+  sources: [{
+    fields: [
+      { name: 'priority', fieldId: field._id }  // Correct ID
+    ]
+  }]
+})
+```
+
+### Error: "Permission Denied"
+
+**Cause:** Don't have permission to create insights or access workflows.
+
+**Solution:**
+- Check workspace permissions
+- Verify access to all workflows in sources
+- Contact workspace administrator
+
+### Insight Created But Returns No Data
+
+**Causes:**
+1. No activities match WHERE clause
+2. JOIN eliminates all rows
+3. Field values are NULL
+
+**Solutions:**
+
+1. **Check activity count:**
+```javascript
+list_activities({
+  workflowId: 'workflow-id',
+  limit: 1
+})
+```
+
+2. **Simplify query to test:**
+```sql
+-- Start simple
+SELECT * FROM tasks LIMIT 10
+
+-- Then add filters one by one
+SELECT * FROM tasks WHERE priority = 'High' LIMIT 10
+```
+
+3. **Use LEFT JOIN instead of INNER JOIN:**
+```sql
+-- Shows all tasks, even without projects
+LEFT JOIN projects ON tasks.projectId = projects.id
+```
+
+### JOIN Not Working
+
+**Cause:** ActivityLink field ID used instead of activity ID.
+
+**Solution:**
+
+```javascript
+// Correct: Join on activity _id
+sources: [
+  {
+    name: 'projects',
+    fields: [
+      { name: 'id', meta: '_id' }  // Use _id for joins
+    ]
+  }
+],
+query: 'LEFT JOIN projects ON tasks.projectId = projects.id'
+
+// Note: projectId field should contain activity ID, not field ID
+```
+
+### Aggregation Returns Unexpected Results
+
+**Cause:** Missing GROUP BY or incorrect grouping.
+
+**Solution:**
+
+```sql
+-- Correct: Group by all non-aggregated columns
+SELECT priority, COUNT(*) AS count
+FROM tasks
+GROUP BY priority
+
+-- Incorrect: Missing GROUP BY
+SELECT priority, COUNT(*) AS count  -- ❌ Error
+FROM tasks
+```
+
+## Integration with Other Tools
+
+### With preview_insight
+
+Test before creating:
+
+```javascript
+// 1. Preview first
+preview_insight({
+  sources: [...],
+  query: 'SELECT ...'
+})
+
+// 2. If successful, create
+create_insight({
+  name: 'My Insight',
+  sources: [...],
+  query: 'SELECT ...'
+})
+```
+
+### With get_insight_data
+
+Execute after creation:
+
+```javascript
+// 1. Create insight
+const result = create_insight({...})
+// Returns: { insightId: '...' }
+
+// 2. Get data
+get_insight_data({
+  insightId: result.insightId
+})
+```
+
+### With get_workflow_schema
+
+Get field IDs:
+
+```javascript
+// 1. Get schema
+const schema = get_workflow_schema({
+  workflowId: 'workflow-id'
+})
+
+// 2. Map fields to IDs
+const fieldMappings = schema.fields
+  .filter(f => f.key)
+  .map(f => ({
+    name: f.key,
+    fieldId: f._id
+  }))
+
+// 3. Use in insight
+create_insight({
+  sources: [{
+    workflowId: 'workflow-id',
+    fields: fieldMappings
+  }],
+  query: '...'
+})
+```
+
+### With list_workflows
+
+Find workflow IDs:
+
+```javascript
+// 1. List workflows
+const workflows = list_workflows()
+
+// 2. Find specific workflows
+const tasks = workflows.find(w => w.name === 'Tasks')
+const projects = workflows.find(w => w.name === 'Projects')
+
+// 3. Create insight
+create_insight({
+  sources: [
+    { name: 'tasks', workflowId: tasks._id, ... },
+    { name: 'projects', workflowId: projects._id, ... }
+  ],
+  query: '...'
+})
+```
+
+## Summary
+
+**Key Takeaways:**
+1. 🔍 **SQL queries** - Full SQL syntax over workflow data
+2. 🔗 **Cross-workflow joins** - Relate data across workflows
+3. 📊 **Aggregations** - COUNT, SUM, AVG, MIN, MAX
+4. 🔑 **Meta fields** - Built-in activity properties (_id, name, created, etc.)
+5. 🧪 **Preview first** - Test queries with preview_insight
+6. 🔒 **Public option** - Share insights without authentication
+7. 📈 **Real-time** - Insights update as activity data changes
+
+**Quick Decision Tree:**
+
+```
+Need to create an insight?
+│
+├─ Single workflow? → Use one source, simple SELECT
+├─ Multiple workflows? → Use multiple sources with JOIN
+├─ Count/aggregate? → Use GROUP BY with COUNT/SUM/AVG
+├─ Filter data? → Add WHERE clause
+├─ Sort results? → Add ORDER BY
+├─ Complex query? → Test with preview_insight first
+└─ Share publicly? → Set public: true
+```
+
+## Additional Resources
+
+- See `preview-insight-skill` for testing queries
+- See `get-insight-data-skill` for executing insights
+- See `remove-insight-skill` for deleting insights
+- See `insight-api` skill for comprehensive Insight API documentation
+- See `hailer-api` skill for Hailer API reference
+- Use `get_workflow_schema` to find field IDs
+- Use `list_workflows` to find workflow IDs