@hailer/mcp 1.3.14 → 1.3.23

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

@@ -1,509 +1,304 @@
 ---
 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
+description: SQL query patterns for Hailer insights — aggregations, filtering, dates, CASE statements, cross-workflow JOINs, and push workflow. Load when designing, writing, or debugging any insight query. Also use for questions about timestamp units (seconds vs ms), reserved column names, source field declarations, phaseLastMove, activityId sidebar wiring, and run_insight ad-hoc vs saved behavior.
 ---
 
+<!-- augmentation-guard: shrink-ok -->
+
 # Insight Query Patterns
 
 <critical-rules>
-## ⚠️ TIMESTAMPS IN INSIGHTS ARE SECONDS (NOT MILLISECONDS!)
+## TIMESTAMP UNITS: PROBE BEFORE ASSUMING
 
-**IMPORTANT:** While the Hailer API uses milliseconds, **insights expose datetime fields as SECONDS** (10-digit numbers like `1768291200`).
+The insight engine is **SQLite**. `strftime('%s', 'now')` returns **seconds** (10-digit unix).
 
-**For date comparisons in WHERE clauses:**
-```sql
--- CORRECT (comparing seconds to seconds)
-WHERE ajankohtaEnd > strftime('%s', 'now')
+**But insight field values can be seconds OR milliseconds:**
 
--- WRONG (comparing seconds to milliseconds - will fail!)
-WHERE ajankohtaEnd > strftime('%s', 'now') * 1000
-```
+| Field source | Unit | How to tell |
+|---|---|---|
+| Plain date/datetime custom fields (fieldId-based) | **seconds** (10-digit) — insight engine's `convert()` divides ALL `date`/`datetime`/`time`/`daterange`/`datetimerange`/`timerange` field values by 1000 unconditionally before inserting into SQLite | 10-digit |
+| Range auto-suffix columns (`<field>Start`, `<field>End`) | **seconds** | 10-digit |
+| `phaseLastMove` (declared with `phaseId`) | **seconds** | 10-digit |
+| Activity meta (`created`, `updated`) | **milliseconds** (13-digit) — meta columns bypass `convert()` | 13-digit |
+| Numeric function fields derived from a datetimerange | **milliseconds** — function fields bypass `convert()` | 13-digit |
 
-**For formatting dates with strftime:**
-```sql
--- CORRECT (field is already in seconds)
-strftime('%Y-%m-%d', dateField, 'unixepoch')
+**Probe first, then write math:**
 
--- WRONG (double-dividing - will show wrong dates)
-strftime('%Y-%m-%d', dateField / 1000, 'unixepoch')
+```sql
+SELECT src.created AS meta_created, src.myDateField AS custom_date, strftime('%s','now') AS now_s
+FROM src LIMIT 1
 ```
 
-**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!
+Compare digit counts: 13 = ms, 10 = s.
 
-**Test before deploying:** Create a diagnostic query to verify:
+**If field is milliseconds (e.g. `meta.created`):**
 ```sql
-SELECT dateField, strftime('%s', 'now') as now_sec,
-       (dateField > strftime('%s', 'now')) as is_future
-FROM source LIMIT 5
+WHERE src.created > strftime('%s','now') * 1000
+strftime('%Y-%m-%d', src.created / 1000, 'unixepoch')
 ```
-</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 = '...'`
-}
+**If field is seconds (most custom date fields):**
+```sql
+WHERE dateField > strftime('%s','now')
+strftime('%Y-%m-%d', dateField, 'unixepoch')
 ```
 
-**Why:** Prevents breaking production apps when modifying insights.
+**Silent failure mode:** assuming seconds when field is ms → `strftime` returns year ~57259 or empty.
 
-**Before modifying production insights:**
-1. Create a TEST duplicate with same sources
-2. Test changes on the duplicate
-3. Apply working changes to production
+**Engine-specific function inventory (SQLite):**
+- Available: `strftime`, `CURRENT_TIMESTAMP`, `COALESCE`, `CASE`, `NULLIF`, `ROUND`, `CAST`
+- Not available: `NOW()`, `UNIX_TIMESTAMP()`, `DATE_TRUNC`, `DATE_FORMAT`
 
----
+**Two gotchas:** (1) Don't alias `activityId` via `AS` — frontend sidebar wires by literal column name. (2) Range fields require explicit `<name>Start` / `<name>End` — bare field name is not selectable.
+</critical-rules>
 
-## Query Basics
+---
 
-Hailer insights use **SQLite syntax**. Queries run over sources you define.
+## Source Metadata — Every Column Must Be Declared
 
-```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"'
-}
-```
+**No auto-exposed metadata columns.** Every column referenced in SQL must be declared in `sources[].fields[]` with either `fieldId` or `meta`. Selecting without a matching declaration returns SQLite `no such column` (code 127).
 
-### Source Field Naming Convention
+**Naming convention — keep `activityId` literal.** The Hailer frontend wires row-click → activity sidebar by the literal output column name `activityId`. Any rename (e.g. `SELECT activityId AS id`) silently breaks the sidebar link.
 
-**Use real field names** in source definitions, not generic names:
+### Canonical Fixture
 
-```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
+Gold copy — paste from this block (testspace insight `_id: 6a16d769d9d2a360ab104d30`):
 
-// BAD - Generic names, confusing
+```javascript
+// sources[0].fields[] — declare every column you'll SELECT
 fields: [
-  { name: 'activityId', fieldId: FieldIds.invoiceNumber },
-  { name: 'date', fieldId: FieldIds.invoiceDate },
-  { name: 'link', fieldId: FieldIds.customer }
+  { name: 'activityId',      meta: '_id' },          // unaliased in SELECT — sidebar wiring
+  { name: 'activityName',    meta: 'name' },
+  { name: 'createdByUserId', meta: 'createdBy' },
+  { name: 'createdTime',     meta: 'created' },       // unix ms (13-digit)
+  { name: 'updatedTime',     meta: 'updated' },       // unix ms (13-digit)
+  { name: 'priority',        meta: 'priority' },
+  { name: 'phaseId',         meta: 'phaseId' },
+  { name: 'phaseName',       meta: 'phaseName' },
+  { name: 'workflowId',      meta: 'workflowId' },
+  { name: 'workflowName',    meta: 'workflowName' },
+
+  // Workflow fields by fieldId — daterange/datetimerange/timerange auto-expose <name>Start / <name>End
+  { name: 'aika',     fieldId: FieldIds.aika },            // datetime → seconds
+  { name: 'aikaväli', fieldId: FieldIds.aikavali },        // timerange → aikaväliStart / aikaväliEnd (seconds)
+  { name: 'ajanjakso',fieldId: FieldIds.ajanjakso },       // daterange → ajanjaksoStart / ajanjaksoEnd (seconds)
+
+  // One phaseLastMove declaration per phase you care about
+  { name: 'movedToLastPhase', meta: 'phaseLastMove', phaseId: PhaseIds.last_phase },
+  { name: 'movedToNewPhase',  meta: 'phaseLastMove', phaseId: PhaseIds.new_phase },
 ]
 ```
 
----
+**Empirical magnitudes (2026-05-27):** `createdTime`/`updatedTime` = 13-digit ms; `aika`/`*Start`/`*End`/`movedTo*` = 10-digit seconds.
 
-## 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 |
+### Declarable Meta Values
 
----
+| `meta` value | SQL type | Notes |
+|---|---|---|
+| `_id` | TEXT | Activity ID — required for cross-workflow JOINs |
+| `name` | TEXT | Activity display name |
+| `created` | INTEGER | Created timestamp — **milliseconds (13-digit)** |
+| `updated` | INTEGER | Updated timestamp — **milliseconds (13-digit)** |
+| `phaseId` | TEXT | Current phase ID |
+| `phaseName` | TEXT | Current phase display name |
+| `priority` | INTEGER | Activity priority |
+| `team` | TEXT | Team ID |
+| `uid` | TEXT | BROKEN — always NULL at runtime. Use `createdBy` instead. |
+| `createdBy` | TEXT | Creator user ID |
+| `workflowId` | TEXT | Workflow ID |
+| `workflowName` | TEXT | Workflow name |
+| `phaseLastMove` | INTEGER | Timestamp the activity entered the phase — **seconds**. Requires `phaseId` sub-key. A declaration without `phaseId` returns `null` for every row. Declare one per phase you want to track. |
 
-## Date Handling
+**`completedOn` is NOT a valid insight `meta:` value** — server rejects it. Workaround for "when did this activity reach the endpoint phase": declare a `phaseLastMove` source field with the endpoint phase's `phaseId`.
 
-**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.
+## Insight Design — Pick the Shape Deliberately
 
-### Range Fields (daterange, datetimerange, timerange)
+**Shape A — Dimensional rows (consumer aggregates)**
+- SELECT every dimension the consumer might group or filter by
+- No `GROUP BY` (or only fine grain)
+- Fits: custom dashboard apps, flexible drill-down
 
-For range field types, Hailer automatically exposes **Start** and **End** suffixes.
+**Shape B — Pre-aggregated summary (SQL groups, consumer plots as-is)**
+- `GROUP BY` in the query
+- Fits: fixed charts, simple reports, KPI cards
 
-| 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 |
+**run_insight ad-hoc cap:** `run_insight` in ad-hoc mode caps at ~200 source rows. Aggregations in ad-hoc are based on at most 200 rows. Create the insight and call `run_insight` with `insightId` to get full results.
 
-**Note:** `timerange` stores full timestamps, not just time. To extract just the time portion, use SQLite time functions.
+**run_insight ad-hoc returns null/0 for ActivityLink columns and JOINs.** Real-world example: a WHERE on an ActivityLink column returned 0 rows ad-hoc, 13,135 rows via saved `run_insight`. Never trust ad-hoc for row counts or column values when the query uses ActivityLink fields.
 
-**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
-  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
-  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) / 60 as duration_minutes
-FROM events
-WHERE ajankohtaStart >= strftime('%s', 'now')
-```
+## Reserved Words as Source Field `name`
 
-**Naming convention:** `{fieldName}Start` and `{fieldName}End` are auto-generated.
+Reserved SQL keywords in source `name` cause **loud `SQLITE_ERROR: near "<word>": syntax error` (code 127)** — not silent NULL. The failure is at `CREATE TABLE` time.
 
-**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
+| Source `name` | Result |
+|---|---|
+| `date`, `store`, `time`, `user` | ✅ safe |
+| `order`, `group`, `select`, `where`, `from` | ❌ breaks table creation |
 
-### 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
-```
+Quoting does not save you — rename the source `name`.
 
 ---
 
-## CASE Statements
+## Aggregate NULL Behavior
 
-### CASE in Aggregation (count by status)
-```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
-```
+| Function | NULL behavior |
+|---|---|
+| `COUNT(*)` | counts every row (NULLs included) |
+| `COUNT(col)` | excludes rows where `col IS NULL` |
+| `COUNT(DISTINCT col)` | excludes NULLs and duplicates |
+| `SUM(col)` | NULLs contribute nothing |
+| `AVG(col)` | excludes NULLs from both numerator and denominator |
 
 ---
 
-## JOINs
-
-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'
-}
-```
-
-### 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"
-```
+## Query Basics
 
-### Three-Way JOIN (Tasks -> Topics -> Projects)
-```javascript
+```typescript
 {
   sources: [
     {
+      workflowId: WorkflowIds.tasks_abc,
       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: 'title', 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' }
+        { name: 'priority', fieldId: Tasks_FieldIds.priority_def }
       ]
     }
   ],
-  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
-  `
+  query: 'SELECT title, priority FROM t WHERE priority = "High"'
 }
 ```
 
-### User ID → Username Conversion
+**Finnish characters in `AS "..."` aliases are fine** — `AS "Päivämäärä"` works. Only bare identifiers (source `name`, CTE names) must stay ASCII.
 
-**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
-```
+## Date Handling
+
+**Always run the probe first.** Summary:
+- Custom date fields (fieldId-based): **seconds** (10-digit) — `convert()` divides unconditionally
+- Activity meta (`created`, `updated`): **milliseconds** (13-digit)
+- `strftime('%s', 'now')` returns seconds
 
-**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
+-- Field is seconds — use directly
+strftime('%Y-%m-%d', dateField, 'unixepoch') AS date_formatted
 
--- Then select with COALESCE for clean output
-COALESCE(em.name, '') AS Event_Manager,
-COALESCE(pm.name, '') AS Production_Manager
+-- Meta created/updated — divide by 1000
+strftime('%Y-%m-%d', created / 1000, 'unixepoch') AS date_formatted
 ```
 
-**Why COALESCE?** User fields can be empty - COALESCE returns empty string instead of NULL for cleaner display.
+### Range Fields (daterange, datetimerange, timerange)
 
-**Common mistake:** Trying to add `user` as a source - don't do this! It's built-in.
+All range field types auto-expose `<name>Start` / `<name>End` suffixes in seconds. The bare field name is NOT selectable — selecting it produces `no such column`.
 
-### JOIN Troubleshooting
+```sql
+-- In sources: just the field name
+{ name: 'ajankohta', fieldId: Event_FieldIds.ajankohta_abc }
 
-| 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 |
+-- In queries: use Start/End suffixes
+SELECT ajankohtaStart, ajankohtaEnd,
+       strftime('%d.%m.%Y', ajankohtaStart, 'unixepoch') as start_date
+FROM events
+```
 
-### JOIN Checklist
+### 1970-01 Diagnostic Checklist
 
-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
+1. Shows `1970-01` dates → likely dividing seconds by 1000, or null function-field value
+2. Correct in preview, wrong live → function-field null across most activities (preview hit the few good rows)
+3. Huge negative numbers in date math → mixing ms and seconds units
+4. Empty-string dates casting to 1970 → `CAST('' AS INTEGER) = 0`. Guard: `NULLIF(field, '')`.
 
 ---
 
-## Common Patterns
+## Filtering
 
-### Monthly Trend (with seconds-based date)
 ```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
-```
+-- Filter on stable IDs, not human-editable names
+WHERE phaseId = '${PhaseIds.won}'   -- stable
+-- NOT: WHERE phaseName = 'Won'     -- breaks on rename
 
-### Completion Rate
-```sql
-SELECT
-  ROUND(
-    100.0 * SUM(CASE WHEN phaseName = 'Done' THEN 1 ELSE 0 END) / COUNT(*),
-    1
-  ) as completion_percent
-FROM tasks
-```
+-- Text match
+WHERE priority = "High"
 
-### Percentage of total (window function)
-```sql
-SELECT
-  phaseName,
-  COUNT(*) as count,
-  ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) as percent
-FROM tasks
-GROUP BY phaseName
-```
+-- NULL check
+WHERE assignee IS NOT NULL
 
-### CTE with Hailer date functions
-```sql
-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,
-  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
+-- IN list
+WHERE phaseId IN ('${phase1}', '${phase2}')
+
+-- LIKE pattern
+WHERE title LIKE "%urgent%"
 ```
 
 ---
 
-## Testing Queries
+## CASE Statements with strftime — Type Mismatch Trap
 
-Always preview before adding to insights.ts:
+`strftime('%s', 'now')` returns **TEXT**, not integer. Comparing a numeric unix column against it inside CASE falls back to string ordering — no error, but wrong results.
 
-```javascript
-mcp__hailer__preview_insight({
-  sources: [...],
-  query: "SELECT ..."
-})
+```sql
+-- Dangerous: strftime returns TEXT, comparison is string ordering
+CASE WHEN ts >= strftime('%s','now') THEN 'future' ELSE 'past' END
+
+-- Safe: CAST to INTEGER first
+CASE WHEN ts >= CAST(strftime('%s','now') AS INTEGER) THEN 'future' ELSE 'past' END
 ```
 
-If preview returns data without errors, add to `workspace/insights.ts`.
+Same trap applies to `MIN(strftime('%s','now'), some_integer)` — picks wrong winner via string ordering.
 
 ---
 
-## 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) |
+## Production Insight Guidelines
 
----
+```typescript
+{
+  _id: "...",
+  name: "Bookings - Public (booking-app)",  // Add (APP) suffix if used by app
+  query: `SELECT /* Used by booking-app - do not change field names! */
+    id, name, varattu_tila, ajankohtaStart, ajankohtaEnd
+    FROM varaukset`
+}
+```
 
-## Date Mistakes & What They Look Like
+Before modifying production insights:
+1. Create a TEST duplicate with same sources
+2. Test changes on the duplicate
+3. Apply working changes to production
 
-### 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"
-```
+## Aggregations
 
-### 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!
+SELECT phaseName, COUNT(*) as count
+FROM tasks
+GROUP BY phaseName
 
--- CORRECT (both sides are seconds)
-WHERE created >= strftime('%s', 'now', '-30 days')
+SELECT customerId, COUNT(*) as order_count
+FROM orders
+GROUP BY customerId
+HAVING COUNT(*) > 5
 ```
 
-### 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'
-```
+## GROUP BY Month
 
-### 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"
+-- meta created (ms) — divide by 1000
+SELECT strftime('%Y-%m', created / 1000, 'unixepoch') as month, COUNT(*) as count
+FROM orders
+GROUP BY month
+ORDER BY month
 
--- CORRECT (add timezone offset)
-strftime('%H:%M', created, 'unixepoch', '+2 hours')
+-- custom date field (seconds) — use directly
+SELECT strftime('%Y-%m', closeDate, 'unixepoch') as month, COUNT(*) as count
+FROM orders
+GROUP BY month
 ```
-
-### 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