@hailer/mcp 1.1.16 → 1.1.17-beta.1

package/.claude/skills/{SDK-insight-queries → sdk-insight-queries}/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: SDK-insight-queries
-description: SQL query patterns for Hailer insights - aggregations, filtering, dates, CASE statements
-version: 1.4.1
-triggers: Insight queries, GROUP BY, COUNT, SUM, date formatting, CASE WHEN
+name: sdk-insight-queries
+description: SQL query patterns for Hailer insights - aggregations, filtering, dates, CASE statements, cross-workflow JOINs
+version: 1.6.0
+triggers: Insight queries, GROUP BY, COUNT, SUM, date formatting, CASE WHEN, JOIN query errors, missing columns, NULL results in insight queries
 ---
 
 # Insight Query Patterns
@@ -112,11 +112,6 @@ fields: [
 ]
 ```
 
-Benefits of real names:
-- Queries are readable and self-documenting
-- Field names match Hailer UI labels
-- Easier debugging and maintenance
-
 ---
 
 ## Available Meta Fields
@@ -139,93 +134,12 @@ Benefits of real names:
 
 ---
 
-## Aggregations
-
-### COUNT
-```sql
-SELECT
-  phaseName,
-  COUNT(*) as count
-FROM tasks
-GROUP BY phaseName
-```
-
-### SUM
-```sql
-SELECT
-  projectName,
-  SUM(hours) as total_hours
-FROM timesheets
-GROUP BY projectName
-```
-
-### AVG, MIN, MAX
-```sql
-SELECT
-  AVG(amount) as avg_amount,
-  MIN(amount) as min_amount,
-  MAX(amount) as max_amount
-FROM orders
-```
-
-### COUNT with DISTINCT
-```sql
-SELECT
-  COUNT(DISTINCT customerId) as unique_customers
-FROM orders
-```
-
----
-
-## Filtering
-
-### WHERE Clauses
-```sql
--- Text match
-WHERE priority = "High"
-
--- Numeric comparison
-WHERE amount > 1000
-
--- NULL check
-WHERE assignee IS NOT NULL
-
--- Multiple conditions
-WHERE priority = "High" AND status != "Done"
-
--- IN list
-WHERE phaseName IN ("Todo", "In Progress")
-
--- LIKE pattern
-WHERE title LIKE "%urgent%"
-```
-
-### HAVING (filter after GROUP BY)
-```sql
-SELECT
-  customerId,
-  COUNT(*) as order_count
-FROM orders
-GROUP BY customerId
-HAVING COUNT(*) > 5
-```
-
----
-
 ## Date Handling
 
 **CRITICAL:** In Hailer insights, all date/time fields are exposed as **Unix timestamps in SECONDS** (10-digit numbers like `1770050954`).
 
 This is different from the Hailer API which uses milliseconds! The insight layer converts automatically.
 
-```sql
--- CORRECT - field is already in seconds, use directly
-strftime('%Y-%m-%d', dateField, 'unixepoch') AS date_formatted
-
--- WRONG - do NOT divide by 1000 (will show wrong dates!)
-strftime('%Y-%m-%d', dateField / 1000, 'unixepoch') AS date_formatted
-```
-
 ### Range Fields (daterange, datetimerange, timerange)
 
 For range field types, Hailer automatically exposes **Start** and **End** suffixes.
@@ -252,20 +166,16 @@ fields: [
 **In queries:** Access with Start/End suffixes (already in seconds):
 ```sql
 SELECT
-  -- All fields are already in seconds - use directly with strftime
   ajankohtaStart,
   ajankohtaEnd,
   strftime('%d.%m.%Y', ajankohtaStart, 'unixepoch') as start_date,
   strftime('%d.%m.%Y', ajankohtaEnd, 'unixepoch') as end_date,
 
   -- Timerange: extract just the time portion
-  tyoaikaStart,
-  tyoaikaEnd,
   strftime('%H:%M', tyoaikaStart, 'unixepoch') as start_time,
   strftime('%H:%M', tyoaikaEnd, 'unixepoch') as end_time,
 
   -- Duration in seconds (both are already seconds)
-  (tyoaikaEnd - tyoaikaStart) as duration_seconds,
   (tyoaikaEnd - tyoaikaStart) / 60 as duration_minutes
 FROM events
 WHERE ajankohtaStart >= strftime('%s', 'now')
@@ -278,16 +188,6 @@ WHERE ajankohtaStart >= strftime('%s', 'now')
 - **Data for Hailer apps** → App receives seconds from insight, may need to multiply by 1000 for API calls
 - **Comparisons** → Compare directly with `strftime('%s', ...)` which also returns seconds
 
-### Format Date (Finnish)
-```sql
-strftime('%d.%m.%Y', dateField, 'unixepoch') AS date_formatted
-```
-
-### Format DateTime
-```sql
-strftime('%d.%m.%Y %H:%M', created, 'unixepoch') AS datetime_formatted
-```
-
 ### Timezone Handling (Finland: +2/+3)
 ```sql
 strftime(
@@ -307,62 +207,11 @@ strftime(
 ) AS local_time
 ```
 
-### Filter by Date Range
-```sql
--- Last 30 days (both sides are seconds)
-WHERE dateField >= strftime('%s', 'now', '-30 days')
-
--- This year
-WHERE strftime('%Y', dateField, 'unixepoch') = strftime('%Y', 'now')
-
--- Specific month
-WHERE strftime('%Y-%m', dateField, 'unixepoch') = '2024-01'
-
--- Between two dates
-WHERE dateField >= strftime('%s', '2024-01-01')
-  AND dateField < strftime('%s', '2024-02-01')
-```
-
-### Group by Month
-```sql
-SELECT
-  strftime('%Y-%m', created, 'unixepoch') as month,
-  COUNT(*) as count
-FROM orders
-GROUP BY strftime('%Y-%m', created, 'unixepoch')
-ORDER BY month
-```
-
 ---
 
 ## CASE Statements
 
-### Simple CASE
-```sql
-SELECT
-  title,
-  CASE priority
-    WHEN 'High' THEN '🔴'
-    WHEN 'Medium' THEN '🟡'
-    WHEN 'Low' THEN '🟢'
-    ELSE '⚪'
-  END as priority_icon
-FROM tasks
-```
-
-### Searched CASE
-```sql
-SELECT
-  title,
-  CASE
-    WHEN amount > 10000 THEN 'Large'
-    WHEN amount > 1000 THEN 'Medium'
-    ELSE 'Small'
-  END as size_category
-FROM orders
-```
-
-### CASE in Aggregation
+### CASE in Aggregation (count by status)
 ```sql
 SELECT
   SUM(CASE WHEN phaseName = 'Done' THEN 1 ELSE 0 END) as completed,
@@ -375,28 +224,101 @@ FROM tasks
 
 ## JOINs
 
-### LEFT JOIN (recommended)
-```sql
-SELECT
-  t.title,
-  p.name as project_name
-FROM tasks t
-LEFT JOIN projects p ON t.projectId = p.id
+When joining workflows via ActivityLink fields, you must:
+1. Include `_id` meta field in **both** source definitions
+2. Join ON the activitylink field value equals target `_id`
+3. Use the activitylink `fieldId` (NOT the key) in the source definition
+
+### Rules
+- Both workflows need `{ name: 'id', meta: '_id' }` in their fields array
+- JOIN condition: `source1.activityLinkFieldName = source2.id`
+- Use LEFT JOIN for optional relationships (activitylink can be null)
+- Use INNER JOIN only when the relationship must exist
+
+### Correct Example
+```javascript
+// Players workflow has "club" field (activitylink to Clubs workflow)
+{
+  sources: [
+    {
+      name: 'p',
+      workflowId: '68446dc05b30685f67c6fcd4',
+      fields: [
+        { name: 'player_name', meta: 'name' },
+        { name: 'id', meta: '_id' },              // Required!
+        { name: 'club', fieldId: '684d5e45...' }  // ActivityLink field
+      ]
+    },
+    {
+      name: 'c',
+      workflowId: '691ea936ccb6bdeebc0cbf77',
+      fields: [
+        { name: 'club_name', meta: 'name' },
+        { name: 'id', meta: '_id' }               // Required!
+      ]
+    }
+  ],
+  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
+}
 ```
 
-**Requirements:**
-- Both sources need `{ name: 'id', meta: '_id' }`
-- Join on activitylink field = target id
+### Wrong Example
+```javascript
+// WRONG - Missing _id in clubs source
+{
+  sources: [
+    {
+      name: 'c',
+      workflowId: 'clubs-id',
+      fields: [
+        { name: 'club_name', meta: 'name' }
+        // Missing: { name: 'id', meta: '_id' }
+      ]
+    }
+  ],
+  query: '... LEFT JOIN c ON p.club = c.id'
+}
+// Error: "no such column: c.id"
+```
 
-### Multiple JOINs
-```sql
-SELECT
-  t.title,
-  p.name as project_name,
-  c.name as customer_name
-FROM tasks t
-LEFT JOIN projects p ON t.projectId = p.id
-LEFT JOIN customers c ON p.customerId = c.id
+### Three-Way JOIN (Tasks -> Topics -> Projects)
+```javascript
+{
+  sources: [
+    {
+      name: 't',
+      workflowId: 'tasks-workflow-id',
+      fields: [
+        { name: 'task_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'topic', fieldId: 'topic-field-id' }
+      ]
+    },
+    {
+      name: 'top',
+      workflowId: 'topics-workflow-id',
+      fields: [
+        { name: 'topic_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'project', fieldId: 'project-field-id' }
+      ]
+    },
+    {
+      name: 'p',
+      workflowId: 'projects-workflow-id',
+      fields: [
+        { name: 'project_name', meta: 'name' },
+        { name: 'id', meta: '_id' }
+      ]
+    }
+  ],
+  query: `
+    SELECT t.task_name, top.topic_name, p.project_name
+    FROM t
+    LEFT JOIN top ON t.topic = top.id
+    LEFT JOIN p ON top.project = p.id
+  `
+}
 ```
 
 ### User ID → Username Conversion
@@ -419,126 +341,38 @@ LEFT JOIN user AS m ON m._id = t.manager
 -- Each user field needs its own JOIN with unique alias
 LEFT JOIN user AS em ON em._id = t.event_manager
 LEFT JOIN user AS pm ON pm._id = t.production_manager
-LEFT JOIN user AS tm ON tm._id = t.ticketing_manager
 
 -- Then select with COALESCE for clean output
 COALESCE(em.name, '') AS Event_Manager,
-COALESCE(pm.name, '') AS Production_Manager,
-COALESCE(tm.name, '') AS Ticketing_Manager
+COALESCE(pm.name, '') AS Production_Manager
 ```
 
 **Why COALESCE?** User fields can be empty - COALESCE returns empty string instead of NULL for cleaner display.
 
 **Common mistake:** Trying to add `user` as a source - don't do this! It's built-in.
 
-See `insight-join-patterns` skill for detailed JOIN patterns.
-
----
-
-## Sorting & Limiting
-
-### ORDER BY
-```sql
-SELECT * FROM tasks
-ORDER BY created DESC
-
--- Multiple columns
-ORDER BY priority ASC, created DESC
-```
-
-### LIMIT
-```sql
-SELECT * FROM tasks
-ORDER BY created DESC
-LIMIT 10
-
--- With offset (pagination)
-LIMIT 10 OFFSET 20
-```
-
----
-
-## String Functions
-
-```sql
--- Concatenate
-SELECT title || ' - ' || phaseName as combined FROM tasks
-
--- Upper/Lower
-SELECT UPPER(title), LOWER(status) FROM tasks
-
--- Substring
-SELECT SUBSTR(title, 1, 50) as short_title FROM tasks
-
--- Replace
-SELECT REPLACE(title, 'OLD', 'NEW') FROM tasks
-
--- Trim
-SELECT TRIM(title) FROM tasks
+### JOIN Troubleshooting
 
--- Length
-SELECT title, LENGTH(title) as title_length FROM tasks
-```
-
----
-
-## NULL Handling
-
-```sql
--- COALESCE (first non-null)
-SELECT COALESCE(assignee, 'Unassigned') as assignee FROM tasks
-
--- IFNULL (SQLite specific)
-SELECT IFNULL(amount, 0) as amount FROM orders
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `no such column: c.id` | Missing `{ name: 'id', meta: '_id' }` in target source | Add `_id` meta to that source |
+| `no such column: p.club` | ActivityLink field not in source fields array | Add field with correct `fieldId` from `get_workflow_schema` |
+| NULL results for joined data | ActivityLink is empty for some activities (expected with LEFT JOIN) | Use INNER JOIN if you only want activities with relationships |
 
--- NULLIF (return NULL if equal)
-SELECT NULLIF(status, 'None') as status FROM tasks
-```
-
----
-
-## Subqueries
-
-```sql
--- In WHERE
-SELECT * FROM tasks
-WHERE projectId IN (
-  SELECT id FROM projects WHERE status = 'Active'
-)
+### JOIN Checklist
 
--- As column
-SELECT
-  title,
-  (SELECT COUNT(*) FROM subtasks s WHERE s.parentId = t.id) as subtask_count
-FROM tasks t
-```
+Before creating an insight with JOINs:
+- [ ] Both workflow sources include `{ name: 'id', meta: '_id' }`
+- [ ] ActivityLink field uses `fieldId` (NOT `key`)
+- [ ] JOIN condition uses column names from sources (e.g., `p.club = c.id`)
+- [ ] Using LEFT JOIN (unless relationship is required)
+- [ ] Tested with `preview_insight` first
 
 ---
 
 ## Common Patterns
 
-### Count by Phase
-```sql
-SELECT
-  phaseName,
-  COUNT(*) as count
-FROM tasks
-GROUP BY phaseName
-ORDER BY count DESC
-```
-
-### Sum by Customer
-```sql
-SELECT
-  c.name as customer,
-  SUM(o.amount) as total
-FROM orders o
-LEFT JOIN customers c ON o.customerId = c.id
-GROUP BY c.name
-ORDER BY total DESC
-```
-
-### Monthly Trend
+### Monthly Trend (with seconds-based date)
 ```sql
 SELECT
   strftime('%Y-%m', created, 'unixepoch') as month,
@@ -560,49 +394,8 @@ SELECT
 FROM tasks
 ```
 
----
-
-## Advanced Patterns
-
-### Window Functions
-
-Window functions perform calculations across rows without collapsing them (unlike GROUP BY).
-
+### Percentage of total (window function)
 ```sql
--- Row numbers (ranking)
-SELECT
-  name,
-  amount,
-  ROW_NUMBER() OVER (ORDER BY amount DESC) as rank
-FROM orders
-
--- Running total
-SELECT
-  name,
-  amount,
-  SUM(amount) OVER (ORDER BY created) as running_total
-FROM orders
-
--- Rank within groups (top 3 per customer)
-SELECT * FROM (
-  SELECT
-    customerName,
-    name,
-    amount,
-    ROW_NUMBER() OVER (PARTITION BY customerName ORDER BY amount DESC) as rank
-  FROM orders
-)
-WHERE rank <= 3
-
--- Compare to previous row
-SELECT
-  name,
-  amount,
-  LAG(amount) OVER (ORDER BY created) as previous_amount,
-  amount - LAG(amount) OVER (ORDER BY created) as change
-FROM orders
-
--- Percentage of total
 SELECT
   phaseName,
   COUNT(*) as count,
@@ -611,28 +404,8 @@ FROM tasks
 GROUP BY phaseName
 ```
 
-**Available window functions:**
-- `ROW_NUMBER()`, `RANK()`, `DENSE_RANK()` - rankings
-- `LAG(col)`, `LEAD(col)` - previous/next row values
-- `SUM() OVER`, `COUNT() OVER`, `AVG() OVER` - running aggregates
-- `FIRST_VALUE()`, `LAST_VALUE()` - boundary values
-- `NTILE(n)` - divide into n buckets
-
-### CTEs (WITH Clauses)
-
-CTEs make complex queries readable by breaking them into named steps.
-
+### CTE with Hailer date functions
 ```sql
--- Simple CTE
-WITH active_orders AS (
-  SELECT * FROM orders
-  WHERE phaseName != 'Cancelled'
-)
-SELECT customerName, SUM(amount) as total
-FROM active_orders
-GROUP BY customerName
-
--- Multiple CTEs
 WITH
   monthly_sales AS (
     SELECT
@@ -647,60 +420,11 @@ WITH
 SELECT
   ms.month,
   ms.total,
-  ma.avg_total,
   CASE WHEN ms.total > ma.avg_total THEN 'Above' ELSE 'Below' END as vs_avg
 FROM monthly_sales ms, monthly_avg ma
 ORDER BY ms.month
-
--- CTE for cleaner JOINs
-WITH
-  customer_totals AS (
-    SELECT customerId, SUM(amount) as total_spent
-    FROM orders
-    GROUP BY customerId
-  )
-SELECT
-  c.name,
-  ct.total_spent
-FROM customers c
-LEFT JOIN customer_totals ct ON c.id = ct.customerId
-ORDER BY ct.total_spent DESC
-```
-
-### UNION (Combining Results)
-
-Combine results from multiple queries.
-
-```sql
--- UNION (removes duplicates)
-SELECT name, 'Task' as type FROM tasks
-UNION
-SELECT name, 'Project' as type FROM projects
-
--- UNION ALL (keeps duplicates, faster)
-SELECT name, amount, 'Invoice' as type FROM invoices
-UNION ALL
-SELECT name, amount, 'Quote' as type FROM quotes
-
--- Combined report from multiple workflows
-SELECT
-  'This Month' as period,
-  COUNT(*) as count,
-  SUM(amount) as total
-FROM orders
-WHERE created >= strftime('%s', 'now', 'start of month')
-UNION ALL
-SELECT
-  'Last Month' as period,
-  COUNT(*) as count,
-  SUM(amount) as total
-FROM orders
-WHERE created >= strftime('%s', 'now', 'start of month', '-1 month')
-  AND created < strftime('%s', 'now', 'start of month')
 ```
 
-**Note:** UNION requires same number of columns with compatible types.
-
 ---
 
 ## Testing Queries
@@ -756,7 +480,6 @@ WHERE created >= strftime('%s', 'now', '-30 days') * 1000
 
 -- CORRECT (both sides are seconds)
 WHERE created >= strftime('%s', 'now', '-30 days')
--- 1705312800 >= 1705312800 → correct comparison
 ```
 
 ### Mistake 3: timerange is NOT minutes
@@ -776,7 +499,6 @@ strftime('%H:%M', created, 'unixepoch')
 
 -- CORRECT (add timezone offset)
 strftime('%H:%M', created, 'unixepoch', '+2 hours')
--- Shows "10:30" (or use +3 during summer time)
 ```
 
 ### Quick Debug