@hailer/mcp 1.1.11 → 1.1.13

package/.claude/skills/SDK-insight-queries/SKILL.md

@@ -1,787 +0,0 @@
----
-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
----
-
-# Insight Query Patterns
-
-<critical-rules>
-## ⚠️ TIMESTAMPS IN INSIGHTS ARE SECONDS (NOT MILLISECONDS!)
-
-**IMPORTANT:** While the Hailer API uses milliseconds, **insights expose datetime fields as SECONDS** (10-digit numbers like `1768291200`).
-
-**For date comparisons in WHERE clauses:**
-```sql
--- CORRECT (comparing seconds to seconds)
-WHERE ajankohtaEnd > strftime('%s', 'now')
-
--- WRONG (comparing seconds to milliseconds - will fail!)
-WHERE ajankohtaEnd > strftime('%s', 'now') * 1000
-```
-
-**For formatting dates with strftime:**
-```sql
--- CORRECT (field is already in seconds)
-strftime('%Y-%m-%d', dateField, 'unixepoch')
-
--- WRONG (double-dividing - will show wrong dates)
-strftime('%Y-%m-%d', dateField / 1000, 'unixepoch')
-```
-
-**Quick rules for insights:**
-- `dateField` → already in seconds, use directly with strftime
-- `strftime('%s', 'now')` → returns seconds, compare directly with dateField
-- Do NOT multiply or divide by 1000!
-
-**Test before deploying:** Create a diagnostic query to verify:
-```sql
-SELECT dateField, strftime('%s', 'now') as now_sec,
-       (dateField > strftime('%s', 'now')) as is_future
-FROM source LIMIT 5
-```
-</critical-rules>
-
----
-
-## Production Insight Guidelines
-
-**If an insight is used by an app, document it:**
-
-```typescript
-{
-  _id: "...",
-  name: "Tilavaraukset - Public",  // Add (APP) suffix if used by app
-  // Or: name: "Tilavaraukset - Public (tilavaraus-app)",
-  query: `SELECT /* Used by tilavaraus-app - do not change field names! */
-    id, name, varattu_tila, ajankohtaStart, ajankohtaEnd
-    FROM varaukset
-    WHERE phaseId = '...'`
-}
-```
-
-**Why:** Prevents breaking production apps when modifying insights.
-
-**Before modifying production insights:**
-1. Create a TEST duplicate with same sources
-2. Test changes on the duplicate
-3. Apply working changes to production
-
----
-
-## Query Basics
-
-Hailer insights use **SQLite syntax**. Queries run over sources you define.
-
-```typescript
-{
-  sources: [
-    {
-      workflowId: WorkflowIds.tasks_abc,
-      name: 't',  // Alias for queries
-      fields: [
-        { name: 'title', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'priority', fieldId: Tasks_FieldIds.priority_def }
-      ]
-    }
-  ],
-  query: 'SELECT title, priority FROM t WHERE priority = "High"'
-}
-```
-
-### Source Field Naming Convention
-
-**Use real field names** in source definitions, not generic names:
-
-```typescript
-// GOOD - Real field names, matches Hailer UI
-fields: [
-  { name: 'nro', fieldId: FieldIds.invoiceNumber },
-  { name: 'pvm', fieldId: FieldIds.invoiceDate },
-  { name: 'asiakas', fieldId: FieldIds.customer }
-]
-// Query: SELECT nro, pvm, asiakas FROM invoices
-
-// BAD - Generic names, confusing
-fields: [
-  { name: 'activityId', fieldId: FieldIds.invoiceNumber },
-  { name: 'date', fieldId: FieldIds.invoiceDate },
-  { name: 'link', fieldId: FieldIds.customer }
-]
-```
-
-Benefits of real names:
-- Queries are readable and self-documenting
-- Field names match Hailer UI labels
-- Easier debugging and maintenance
-
----
-
-## Available Meta Fields
-
-| Meta | Description | Example |
-|------|-------------|---------|
-| `_id` | Activity ID | Required for JOINs |
-| `name` | Activity name | Display name |
-| `created` | Created timestamp | Unix seconds |
-| `updated` | Updated timestamp | Unix seconds |
-| `phaseId` | Current phase ID | For phase filtering |
-| `phaseName` | Current phase name | Human readable |
-| `workflowId` | Workflow ID | |
-| `workflowName` | Workflow name | |
-| `createdBy` | Creator user ID | |
-| `uid` | User ID | |
-| `team` | Team ID | |
-| `priority` | Priority value | |
-| `phaseLastMove` | Last phase change | Unix seconds |
-
----
-
-## 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.
-
-| Field Type | In Insight SQL |
-|------------|----------------|
-| `date` | Seconds (10-digit) |
-| `datetime` | Seconds (10-digit) |
-| `time` | Seconds (10-digit) |
-| `daterange` | Start/End in seconds |
-| `datetimerange` | Start/End in seconds |
-| `timerange` | Start/End in seconds |
-
-**Note:** `timerange` stores full timestamps, not just time. To extract just the time portion, use SQLite time functions.
-
-**In sources:** Use just the field name:
-```typescript
-fields: [
-  { name: 'ajankohta', fieldId: Event_FieldIds.ajankohta_abc },  // daterange/datetimerange
-  { name: 'tyoaika', fieldId: Event_FieldIds.tyoaika_def }       // timerange
-]
-```
-
-**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')
-```
-
-**Naming convention:** `{fieldName}Start` and `{fieldName}End` are auto-generated.
-
-**IMPORTANT: When to convert vs keep raw:**
-- **Display only** (human-readable reports) → Use `strftime()` to format
-- **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(
-  '%d.%m.%Y %H:%M',
-  created,
-  'unixepoch',
-  CASE
-    WHEN created >= (
-      SELECT strftime('%s', date(strftime('%Y', created, 'unixepoch') || '-03-31', 'weekday 0', '-7 days', '03:00'))
-    )
-    AND created < (
-      SELECT strftime('%s', date(strftime('%Y', created, 'unixepoch') || '-10-31', 'weekday 0', '-7 days', '04:00'))
-    )
-    THEN '+3 hours'
-    ELSE '+2 hours'
-  END
-) 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
-```sql
-SELECT
-  SUM(CASE WHEN phaseName = 'Done' THEN 1 ELSE 0 END) as completed,
-  SUM(CASE WHEN phaseName != 'Done' THEN 1 ELSE 0 END) as pending,
-  COUNT(*) as total
-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
-```
-
-**Requirements:**
-- Both sources need `{ name: 'id', meta: '_id' }`
-- Join on activitylink field = target 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
-```
-
-### User ID → Username Conversion
-
-**IMPORTANT:** The `user` table is a **pseudo-table** in Hailer insights. You don't need to declare it as a source - just JOIN directly.
-
-```sql
--- Convert user ID fields to display names
-SELECT
-  t.title,
-  COALESCE(u.name, '') AS Assignee_Name,
-  COALESCE(m.name, '') AS Manager_Name
-FROM tasks t
-LEFT JOIN user AS u ON u._id = t.assignee
-LEFT JOIN user AS m ON m._id = t.manager
-```
-
-**Pattern for multiple user fields:**
-```sql
--- 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
-```
-
-**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
-
--- 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
-
--- 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'
-)
-
--- As column
-SELECT
-  title,
-  (SELECT COUNT(*) FROM subtasks s WHERE s.parentId = t.id) as subtask_count
-FROM tasks t
-```
-
----
-
-## 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
-```sql
-SELECT
-  strftime('%Y-%m', created, 'unixepoch') as month,
-  COUNT(*) as count,
-  SUM(amount) as total
-FROM orders
-WHERE created > strftime('%s', 'now', '-12 months')
-GROUP BY month
-ORDER BY month
-```
-
-### Completion Rate
-```sql
-SELECT
-  ROUND(
-    100.0 * SUM(CASE WHEN phaseName = 'Done' THEN 1 ELSE 0 END) / COUNT(*),
-    1
-  ) as completion_percent
-FROM tasks
-```
-
----
-
-## Advanced Patterns
-
-### Window Functions
-
-Window functions perform calculations across rows without collapsing them (unlike GROUP BY).
-
-```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,
-  ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) as percent
-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.
-
-```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
-      strftime('%Y-%m', created, 'unixepoch') as month,
-      SUM(amount) as total
-    FROM orders
-    GROUP BY month
-  ),
-  monthly_avg AS (
-    SELECT AVG(total) as avg_total FROM monthly_sales
-  )
-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
-
-Always preview before adding to insights.ts:
-
-```javascript
-mcp__hailer__preview_insight({
-  sources: [...],
-  query: "SELECT ..."
-})
-```
-
-If preview returns data without errors, add to `workspace/insights.ts`.
-
----
-
-## Common Mistakes
-
-| Wrong | Right |
-|-------|-------|
-| Using `"` for identifiers | Use `"` for strings, backticks for identifiers if needed |
-| Forgetting `_id` meta for JOINs | Always include `{ name: 'id', meta: '_id' }` |
-| INNER JOIN for optional links | Use LEFT JOIN (links can be null) |
-| Raw timestamps in output | Format with `strftime()` |
-| Skipping preview | Always test with `preview_insight` first |
-| Hardcoding workflow IDs | Use `WorkflowIds` enum |
-| Generic field names (`date`, `id`) | Use real names (`pvm`, `nro`) that match Hailer UI |
-| Using `/ 1000` for dates | Insight fields are already SECONDS - use directly with `strftime()` |
-| Using `* 1000` in WHERE | Both sides are seconds - compare directly |
-| `t.ajankohta` for range fields | Use `t.ajankohtaStart` and `t.ajankohtaEnd` (auto-suffixed for daterange, datetimerange, timerange) |
-
----
-
-## Date Mistakes & What They Look Like
-
-### Mistake 1: Using `/ 1000` (OLD HABIT - DON'T DO THIS!)
-```sql
--- WRONG (insight fields are already in seconds!)
-strftime('%Y-%m-%d', created / 1000, 'unixepoch')
--- Result: "1970-01-21" (wrong - divided seconds by 1000!)
-
--- CORRECT (use field directly)
-strftime('%Y-%m-%d', created, 'unixepoch')
--- Result: "2024-01-15"
-```
-
-### Mistake 2: Using `* 1000` in WHERE
-```sql
--- WRONG (multiplying seconds by 1000 makes comparison fail)
-WHERE created >= strftime('%s', 'now', '-30 days') * 1000
--- 1705312800 >= 1705312800000 → always false!
-
--- CORRECT (both sides are seconds)
-WHERE created >= strftime('%s', 'now', '-30 days')
--- 1705312800 >= 1705312800 → correct comparison
-```
-
-### Mistake 3: timerange is NOT minutes
-```sql
--- WRONG (thinking timerange is minutes from midnight)
-WHERE tyoaikaStart < 480  -- "before 8am"
-
--- CORRECT (timerange is timestamp in seconds - extract hour)
-WHERE strftime('%H', tyoaikaStart, 'unixepoch') < '08'
-```
-
-### Mistake 4: Timezone confusion
-```sql
--- WRONG (UTC time, Finland is +2/+3)
-strftime('%H:%M', created, 'unixepoch')
--- Shows "08:30" when local time is "10:30"
-
--- CORRECT (add timezone offset)
-strftime('%H:%M', created, 'unixepoch', '+2 hours')
--- Shows "10:30" (or use +3 during summer time)
-```
-
-### Quick Debug
-If your dates look wrong:
-1. **Years like 1970** → using `/ 1000` when you shouldn't (field is already seconds)
-2. **No rows returned** → using `* 1000` in WHERE (comparing seconds to huge number)
-3. **Times off by 2-3 hours** → timezone not applied
-4. **Duration calculations** → subtract seconds directly: `(endField - startField) / 60` for minutes