@hailer/mcp 1.3.14 → 1.3.23

package/.claude/skills/hailer-workflow-archetypes/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: hailer-workflow-archetypes
+description: Pick the right Hailer workspace structural skeleton before building — 9 canonical archetypes (Register, Pipeline, Header+LineItems, Booking-Line, Event-Hub, Request-Fulfilment, Approval, Many-to-Many, Recurring Template). Load this skill at design time, before delegating any workflow or field creation.
+---
+
+# Hailer Workflow Archetypes — Catalogue
+
+<!-- Synthesised from 1383 real workflows across 39 sdk-projects workspaces (2026-06-16).
+     This is the WHICH-SHAPE catalogue. HOW to implement each shape lives in the cross-linked skills. -->
+
+**Purpose:** Pick the canonical structural skeleton that fits the design problem, then load the owning mechanic skill for implementation detail. This skill is skeletons — field declarations, function-field bodies, and push/pull commands live in the cross-linked skills listed in the table and in the Cross-links section.
+
+---
+
+## Archetype menu
+
+| Archetype | When to use (one line) | Owning mechanic skill |
+|-----------|------------------------|----------------------|
+| **Register / Ledger** | Master data, lookup catalogs, reference tables, immutable logs | `sdk-ws-config-skill` |
+| **Pipeline** | Single workflow tracking one record through named lifecycle stages | `hailer-design-patterns` |
+| **Header + Line-Items** | Document-level header (order/invoice/BOM) that owns N child rows and needs rollup totals | `sdk-function-fields` (pivot/backlink aggregation) |
+| **Resource-Reservation / Booking-Line** | Booking line sitting between an event/job header and a bookable resource catalog | `sdk-function-fields` (linked-data cross-workflow reads) |
+| **Event-Aggregate Hub** | Central coordinator that fans out to multiple registers and aggregates from 3–8 distinct child workflows | `sdk-function-fields` (linked-data cross-workflow reads) |
+| **Request ↔ Fulfilment** | Two linked workflows with genuinely different lifecycles and owners | `sdk-function-fields` (phase-cascade JSON payload) |
+| **Approval Flow** | Single workflow with a binary approve/reject decision gate as its defining feature | `hailer-design-patterns` |
+| **Many-to-Many Junction** | Pure join table connecting two registers in a M:N relationship — no multi-value field exists in Hailer | `sdk-ws-config-skill` |
+| **Recurring Template** | Template/master record that gets cloned into time-bound per-occurrence instances | `hailer-design-patterns` |
+
+---
+
+### Register / Ledger
+
+**When to use:** Master data, reference tables, lookup catalogs, or immutable event logs that other workflows point at. Records live permanently in one place; phases (if any) are status buckets (Active/Archive), type categories, or year/version slots — never a forward process. Reach for this for customers, products, price lists, locations, employees, taxonomies, and append-only logs.
+
+**Field skeleton:**
+- Name / Title — `string` — primary identifier; often the nameColumnText
+- Code / SKU / Reference — `string` — external/business key
+- Category / Type — `textpredefinedoptions` — single-value dropdown, never an array
+- Unit Price — `numericunit` — for pricing catalogs
+- Parent Reference — `activitylink` — optional single link up a taxonomy/hierarchy (one field = one link)
+- Child Count / Rollup — `function` — optional `<` backlink count/sum of children that link in; synchronous, returns array to reduce
+
+**Phase skeleton:** All — or Active / Archive
+
+**Linking mechanic:** Other workflows link TO a register via their own single-value ActivityLink field. The register itself usually links out 0–1 times (e.g. a parent in a self-referential taxonomy chain). Optional function fields on the register use a `<` backlink variable (`data: [childWorkflowId, fieldId]`) to count or summarize children that link in — returns a same-length array per declared variable, reduced synchronously in the body.
+
+**Owning skill:** `sdk-ws-config-skill`
+
+**Real exemplars:**
+- onelamor / Items (master SKU registry) — `69f9923c72a68c80863bb3c9`
+- #hailer / Products, Services and Licenses — `67dc1b7d3d2c9f6cf9a54657`
+- project-logistics / product_master_data — `69905ff98415a9621a718982`
+- 3pl-pro / VH - Nimikkeistö — `63df86a3eddeece67291f28c`
+
+**Frequency:** Most common archetype fleet-wide. Present in every batch; dominant shape in data-heavy workspaces. Roughly a third to two-thirds of any workspace.
+
+---
+
+### Pipeline
+
+**When to use:** A single workflow whose primary value is tracking one record through named lifecycle stages. Use for sales funnels, task/Kanban boards, production/order execution, ticket queues, project lifecycles, incident/complaint trackers. The phase IS the state; there is no mandatory parent header and no aggregating children (links out, if any, are context references to registers).
+
+**Field skeleton:**
+- Title / Subject — `string`
+- Customer / Subject Link — `activitylink` — single context link to a register
+- Owner / Assignee — `users` — single user field; multiple owners = multiple user fields, never an array
+- Amount / Value — `numericunit` — optional deal/order value
+- Due Date — `date` — Unix timestamp on write
+- Context Value (pulled) — `function` — optional `>` forward-link pulling a value from the single linked register activity
+
+**Phase skeleton:** New / Backlog → In Progress → Review / Waiting → Done / Won → Cancelled / Lost (terminal) → Archive (terminal)
+
+**Linking mechanic:** Phases drive the record forward via `possibleNextPhase` transitions (linear or branching, with terminal endpoint phases for cancel/archive). Cross-workflow data is read-only context: a single-value ActivityLink to a register plus optional `>` forward-link function variables (`data: [linkFieldId, targetFieldId]`) that resolve one linked activity's value. No `<` aggregation — that would make it a header.
+
+**Owning skill:** `hailer-design-patterns`
+
+**Real exemplars:**
+- onelamor / 001. Sales Funnel — `558ef59c7b417df45de6325c`
+- #hailer / Development Tasks — `5c1c9772b0631420d10e0b6a`
+- project-logistics / transport_orders — `69906454686166113617b382`
+
+**Frequency:** In every batch; second/third most common. The default shape for any process that moves.
+
+---
+
+### Header + Line-Items
+
+**When to use:** A document-level header (order, invoice, BOM, quote) that owns N child row activities and needs totals/counts rolled up from them. Use whenever you have an order with order lines, an invoice with invoice rows, a BOM with components — anything where the parent must sum or count what the children hold.
+
+**Field skeleton:**
+- Header: Customer / Supplier — `activitylink` — single link to a CRM/supplier register
+- Header: Total (excl. VAT) — `function` — `<` backlink SUM over child row amounts
+- Header: Row Count — `function` — `<` backlink COUNT of children
+- Row: Parent Header — `activitylink` — the child's single link back to the header (this is the join)
+- Row: Product / Item — `activitylink` — single link to a product register
+- Row: Quantity — `numericunit`
+- Row: Line Total — `function` — `>` forward-link unit price × qty, computed on the row
+
+**Phase skeleton:**
+- Header: Draft → Confirmed → Sent / In Progress → Completed / Invoiced → Cancelled (terminal)
+- Row: All (single flat phase)
+
+**Linking mechanic:** Two workflows. The child row carries ONE single-value ActivityLink field pointing back to the header (`data: [headerWorkflowId]`). The header aggregates via `<` backlink function variables (`data: [rowWorkflowId, rowFieldId]`) — each variable returns a parallel, same-length, same-order array of that field across all linked children; the body sums/counts/zips them synchronously. Multiple parallel `<` variables from the same child workflow are index-aligned (pivot pattern). Never model rows as an array on one field — use a separate row workflow.
+
+**Owning skill:** `sdk-function-fields` (for the `<` backlink pivot aggregation pattern — declare `functionVariables` with `type: '<'`, `data: [rowWorkflowId, rowFieldId]`, reduce the returned array synchronously in the body)
+
+**Real exemplars:**
+- #hailer / Invoicing + Invoice Rows — `67dc1b7d3d2c9f6cf9a5468b / 67dc1b7d3d2c9f6cf9a5468d`
+- onelamor / Purchase orders + Purchase order rows — `68a857b5aa341124b5670239`
+- claude-config-testspace / Orders + OrderLines — `69e5dea5f8cd96dba3411522 / 69e5deacf8cd96dba34115ad`
+
+**Frequency:** In every batch; co-leads with Pipeline as second most common. The backbone of every ERP/finance/order workspace.
+
+---
+
+### Resource-Reservation / Booking-Line
+
+**When to use:** A booking line that sits between an event/job header and a bookable resource catalog — venue room, staff member, equipment, catering product, time slot. Use in event-management, venue-rental, scheduling, and field-service workspaces where each reservation must reference both WHAT is booked (resource) and WHAT it belongs to (event), and the parent rolls reservations up.
+
+**Field skeleton:**
+- Event / Header Link — `activitylink` — single link to the event/job hub
+- Reserved Resource — `activitylink` — single link to the resource register (room/person/equipment/product)
+- Time / Period — `timerange` — or datetimerange object; the slot being held
+- Line Total — `function` — `>` forward-link pulls unit price from the resource, computed on the line
+- Resource Calendar JSON — `function` — optional `<` backlink on the resource register itself, aggregating its own bookings for conflict detection
+
+**Phase skeleton:** Reserved / Preliminary → Confirmed → Cancelled (terminal) → Archive (terminal)
+
+**Linking mechanic:** Two single-value ActivityLink fields on the booking line: one back to the event header, one out to the resource register. The header aggregates the booking lines via `<` backlinks (same as Header + Line-Items). Separately, the resource register often carries its own `<` backlink function that serializes all its reservations into a calendar/availability JSON for overlap checking. A line that needs two possible parents uses an ActivityLink field whose `data[]` allows two target workflows — still one value at a time, never an array.
+
+**Owning skill:** `sdk-function-fields` (for linked-data cross-workflow reads — both `<` backlink on the resource and `>` forward-link on the booking line)
+
+**Real exemplars:**
+- skm / Henkilöresurssivaraukset — `67bc2c9535d8f29758a2fbdd`
+- sunborn-linna / Astiat myyntitilausrivit — `62678581897c430b07400954`
+- veikkaus-arena / Tilavaraukset — `682ac817fba468d857d4991a`
+
+**Frequency:** Pervasive across every venue/event workspace. Structurally a Header + Line-Items child with a second resource link.
+
+---
+
+### Event-Aggregate Hub
+
+**When to use:** The central coordinator record of a workspace — a master event/production/project that fans OUT to several registers (customer, venue, personnel, promoter) AND aggregates IN from 3–8 distinct child booking/line workflows. Use it as the single hub everything else hangs off in event-production, venue, and large project workspaces.
+
+**Field skeleton:**
+- Event Name — `string`
+- Customer — `activitylink` — one of several single context links out
+- Contact Person — `activitylink`
+- Venue / Site — `activitylink`
+- Period — `datetimerange`
+- Reservations Summary (per child type) — `function` — one `<` backlink function PER child workflow (e.g. space, staff, catering, equipment); never one mega-field
+- Grand Total — `function` — `<` sum across child line totals
+
+**Phase skeleton:** Preliminary / Tentative → Confirmed → Published / In Production → Invoiced → Held / Done → Cancelled (terminal) → Archive (terminal)
+
+**Linking mechanic:** Multiple single-value ActivityLink fields out to registers (one field per dimension — three teams = three team fields, never an array). Multiple `<` backlink function variables IN, each scoped to a DIFFERENT child workflow (`data: [childWorkflowId, fieldId]`); each produces its own array, summarized into its own summary field. Phase-cascade function fields can emit JSON to move children when the hub is cancelled/archived. All synchronous; no field holds more than one value.
+
+**Owning skill:** `sdk-function-fields` (for multi-child `<` backlink aggregation and phase-cascade JSON payload pattern)
+
+**Real exemplars:**
+- TKT / Tapahtumavaraukset (event-hub) — `685e3794d97fdb32fb2e1715`
+- nokia-arena / Tuotantovaraukset — `6033b5fc0f6e7900071daa43`
+- #hailer / Change & Configuration Management (cross-linked tracker) — `691356ecdbaed8d0028763ce`
+
+**Frequency:** Recurs as the spine of event/production workspaces. Usually 1–3 per workspace but structurally load-bearing — everything else links to it.
+
+---
+
+### Request ↔ Fulfilment
+
+**When to use:** Two linked workflows: an intake/request side (often a public form or external entry) and a separate fulfilment/execution side that carries the work to completion. Use when the request and the doing-of-it have genuinely different lifecycles and owners (recruitment application vs hiring, service request vs work order, RFQ vs delivery, tender vs contract).
+
+**Field skeleton:**
+- Request: Subject — `string`
+- Request: Requester — `activitylink` — single link to customer/person register
+- Request: Fulfilment Link — `activitylink` — single link to the fulfilment record once spawned
+- Fulfilment: Source Request — `activitylink` — single link back to the originating request
+- Fulfilment: Assignee — `users`
+- Cascade Payload — `function` — optional JSON output consumed by an automation to move/update the partner record
+
+**Phase skeleton:**
+- Request: New → In Review → Approved (spawns) / Rejected
+- Fulfilment: Open → In Progress → Done / Archive
+
+**Linking mechanic:** Each side carries ONE single-value ActivityLink to the other. Phase changes propagate via a phase-cascade function field whose JSON output is read by an external automation (monolith webhook, cron, microservice) that calls `v3.activity.updateMany` on the linked record — function fields cannot move activities themselves (no async/network in isolated-vm). Read-only context flows via `>` forward-link; the actual cascade is automation-driven.
+
+**Owning skill:** `sdk-function-fields` (for the phase-cascade JSON payload pattern — emit a structured payload from the function body; automate the cross-workflow update externally)
+
+**Real exemplars:**
+- gofitness / Huoltopyyntölomake → Huolto — `69dcc1d8d36be8b37cc9e771 / 69a83c19bf7a99ffd0bd8e2c`
+- pohjaset / Pohjaset - Työhakemuslomake → Avoimet työpaikat / Työsopimukset — `67a9b8fe1feff92854dfac87 / 67a9b8fe1feff92854dfac89`
+- skm / Työtarjoukset → Ryhmävaraukset — `68109d4e05b8d02c7ebd0288 / 68109d4e05b8d02c7ebd0277`
+
+**Frequency:** Moderately common. Often blends with Pipeline at the edges — call it Request ↔ Fulfilment only when there are genuinely two linked workflows with a cascade.
+
+---
+
+### Approval Flow
+
+**When to use:** A single workflow whose defining feature is a binary decision gate — Approved vs Rejected as terminal endpoints — usually with an intake phase before and optional fulfilment tail after. Use for leave/vacation requests, expense/reimbursement claims, purchase requisitions, benefit payouts, simple sign-offs. Reach for this over a generic Pipeline when the outcome is a yes/no decision, not a multi-stage progression.
+
+**Field skeleton:**
+- Request Title — `string`
+- Requester / Employee — `activitylink` — single link to employee/customer register
+- Amount / Days Requested — `numericunit`
+- Approver — `users` — single approver field; second approver = a second field, not an array
+- Decision Note — `textarea`
+- Computed Eligibility — `function` — optional `>` forward-link pulling balance/entitlement from the employee register
+
+**Phase skeleton:** Request / Pending → Approved (terminal) / Rejected / Denied (terminal) → (optional) Fulfilled → Archive
+
+**Linking mechanic:** Phases encode the decision: an intake phase with two `possibleNextPhase` targets (approved, rejected), both terminal. Context fields are single-value ActivityLinks plus optional `>` forward-link functions to read the requester's entitlement. No `<` aggregation and no child workflow — that's what separates it from Header + Line-Items and Request ↔ Fulfilment.
+
+**Owning skill:** `hailer-design-patterns`
+
+**Real exemplars:**
+- onelamor / Vacation Requests — `68909d924bd6f64c1e922816`
+- #hailer / Distributed Well-Being Pool — `69e9e8919bfb1d30714f0dfd`
+- nokia-arena / Hankinta (purchase request) — `60349f050f6e790007219617`
+
+**Frequency:** Real and recurring but narrow — frequently collapses into Pipeline. Distinct only when the binary approve/reject gate is the whole point.
+
+---
+
+### Many-to-Many Junction
+
+**When to use:** A pure join table connecting two (or three) registers in a many-to-many relationship — partner↔skill, supplier↔product, project↔supplier, event↔attendee, customer↔license. Use whenever an entity can relate to many of another and vice-versa, since Hailer has no multi-value link. Each junction record represents ONE pairing, with optional payload (level, price override, role) on the join. This is the canonical Hailer answer to "I need multiple X linked to Y".
+
+**Field skeleton:**
+- Parent A — `activitylink` — single link to register A
+- Parent B — `activitylink` — single link to register B
+- Junction Payload — `numericunit` — optional override/qualifier on the pairing (price, level, role)
+- Note — `string` — optional
+
+**Phase skeleton:** All (single flat phase)
+
+**Linking mechanic:** Exactly two (or three) single-value ActivityLink fields, each to a different register, on a flat one-phase workflow. The many-to-many is realized by having MANY junction records — never by an array field. Either parent register can surface its related set via a `<` backlink function reading the junction.
+
+**Owning skill:** `sdk-ws-config-skill`
+
+**Real exemplars:**
+- #hailer / Partner Skills Rows — `69afd2b2712bcca4541105a2`
+- project-logistics / supplier_products — `6998c43064b3290e69db4213`
+- skm / Oppaiden osaamisten linkitys — `68109d4e05b8d02c7ebd026b`
+
+**Frequency:** Recurs wherever entities cross-relate. Small count per workspace but a distinct, reusable structural answer.
+
+---
+
+### Recurring Template
+
+**When to use:** A template/master record that gets cloned or instantiated into time-bound or per-occurrence instances — shift templates spawning shifts, event templates spawning event bookings, recurring-task lists spawning task instances, induction checklists spawning per-employee tasks. Use when the customer reuses a defined structure on a schedule or per-trigger.
+
+**Field skeleton:**
+- Template Name — `string`
+- Resource / Scope Link — `activitylink` — single link to the register the template applies to (store, role, venue)
+- Default Period / Offset — `timerange` — start/end offsets the instance inherits
+- Instantiation Target — `activitylink` — on the request-side workflow: single link selecting which template to spawn from
+- Spawned Instances — `function` — optional `<` backlink count of instances created from this template
+
+**Phase skeleton:**
+- Template: Active / Archived
+- Instance: Planned → Confirmed → Done / Cancelled
+
+**Linking mechanic:** A template workflow holds the definition; an instantiation-request (or a scheduled automation) reads it via a single-value ActivityLink and creates instance activities. **The actual spawning is automation/cron-driven — function fields cannot create activities** (no async/network in isolated-vm). Template↔instance visibility is via single ActivityLink fields plus optional `<` backlink for counting instances. Recurrence cadence lives in the automation, not in the field.
+
+**Owning skill:** `hailer-design-patterns`
+
+**Real exemplars:**
+- logomo / Template + Templaterivit + Tapahtuman luonti templatesta — `699ec588098b9886211555e3 / 699ec589098b9886211555e6 / 699ec519098b988621154cd9`
+- puutarhanikkarit-v2 / Vuoropohja → Työvuoro — `6a034cfc35ef550a424960f4 / 69e1cbba4402eb9de283fab9`
+- pohjaset / Toistuvat tehtävälistat → Toistuvat tehtävät — `67c6f6e6095c5f35125922ef / 67c6f73b095c5f35125925de`
+
+**Frequency:** Rarest of the validated set. Appears in ~6 batches at low counts. Real and worth cataloguing, but the spawn mechanic always depends on an external automation — note that prominently when designing.
+
+---
+
+## Hard guards
+
+These are load-bearing; they override any spec or shortcut that contradicts them.
+
+**No multi-value field types exist in Hailer.** Every field — ActivityLink, users, teams, textpredefinedoptions — holds exactly ONE value. "Multiple X linked to Y" is never solved by an array on one field. The two canonical answers: (a) use multiple separate ActivityLink fields (one per link), or (b) use a Many-to-Many Junction workflow (one record per pairing). If you find yourself writing or thinking `["id1", "id2"]` for any field value, stop — that field type does not exist.
+
+**Function fields are synchronous isolated-vm JavaScript.** No async, no fetch, no import, no TypeScript syntax, no `linkedFrom()`. Cross-workflow reads work ONLY via declared `functionVariables`:
+- `<` backlink (`data: [sourceWorkflowId, fieldId]`) — returns a parallel, same-length array of children's field values; reduce/sum/filter it synchronously in the body
+- `>` forward-link (`data: [linkFieldId, targetFieldId]`) — returns that single linked activity's value
+
+Ad-hoc reads of un-wired activities do not work. Async network access does not work.
+
+**Function fields cannot create or move activities.** Request ↔ Fulfilment cascades, Recurring Template spawns, and Event-Aggregate Hub phase cascades all work by having the function field emit a JSON payload that an **external automation** (monolith webhook, cron, microservice) reads and then calls `v3.activity.updateMany` or `v3.activity.create`. The function field is read-only compute inside isolated-vm; it has no network access to act on its own output.
+
+---
+
+## Cross-links
+
+This skill is the WHICH-SHAPE. The HOW lives in:
+
+- `hailer-design-patterns` — principles for when to split workflows vs keep flat; when to reach for which archetype at a higher level; approval gate and pipeline patterns
+- `sdk-ws-config-skill` — field/phase TypeScript config, push/pull commands, numericunit/textpredefinedoptions formats
+- `sdk-function-fields` — function field body syntax, isolated-vm constraints, `<` backlink aggregation, `>` forward-link, phase-cascade JSON payload, null-return debugging

package/.claude/skills/insight-join-patterns/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: insight-join-patterns
+description: Correct JOIN syntax for Hailer insights with ActivityLink, user, and dropdown fields. Load when writing a cross-workflow insight JOIN, resolving NULL join results, joining user fields to names, or handling polymorphic ActivityLink fields (one field pointing to multiple target workflows). Includes the field-type JOIN matrix, row-multiplication trap for one-to-many backlink JOINs, and how to surface orphan rows when a link target has been deleted.
+---
+
+# Insight JOIN Patterns
+
+**Prerequisite:** Review `sdk-insight-queries` for basic insight syntax and single-workflow queries.
+
+## Core Rules
+
+1. Both workflows need `{ name: 'id', meta: '_id' }` in their fields array
+2. JOIN condition: `source1.activityLinkFieldName = source2.id`
+3. Use LEFT JOIN for optional relationships (activitylink can be null)
+4. Use INNER JOIN only when relationship must exist
+
+**Status: EMPIRICALLY CONFIRMED** — S235 (2026-05-28), 4 calls, 55 populated rows matched. ON-clause syntax verified against a live cross-workflow join (Deals → Accounts).
+
+## Columns Are Declared, Not Built-In
+
+Every SQL column comes from a source's `fields[]` entry — either `{ name: '<your column>', meta: '<key>' }` or `{ name: '<your column>', fieldId: '<field id>' }`. Nothing is auto-injected: if you `SELECT` a column, a source must declare it first, or you get "no such column". The `name` is the SQL column name you choose; `meta`/`fieldId` is where its value comes from.
+
+Valid `meta` keys (activity metadata): `_id`, `name`, `created`, `updated`, `phaseId`, `phaseName`, `phaseLastMove`, `workflowId`, `workflowName`, `team`, `createdBy` (alias `uid`), `priority`. There is **no `activityName` / `activityId` meta** — the activity name is `meta: 'name'`, the id is `meta: '_id'`. Custom fields use `fieldId`, never `meta`.
+
+## Correct Pattern
+
+```javascript
+{
+  sources: [
+    {
+      name: 'p',
+      workflowId: '68446dc05b30685f67c6fcd4',
+      fields: [
+        { name: 'player_name', meta: 'name' },
+        { name: 'id', meta: '_id' },              // Required!
+        { name: 'club', fieldId: '684d5e45...' }  // ActivityLink field — use fieldId, NOT key
+      ]
+    },
+    {
+      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 Pattern
+
+```javascript
+// ❌ WRONG - Missing _id in clubs source → "no such column: c.id"
+{
+  sources: [
+    { name: 'c', workflowId: 'clubs-id', fields: [{ name: 'club_name', meta: 'name' }] }
+    // Missing: { name: 'id', meta: '_id' }
+  ]
+}
+```
+
+---
+
+## Three-Way JOIN
+
+```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
+  `
+}
+```
+
+---
+
+## Troubleshooting
+
+**Error: "no such column: c.id"** — missing `{ name: 'id', meta: '_id' }` in target workflow source.
+
+**Error: "no such column: p.club"** — ActivityLink field not included in source fields array; check you used the correct `fieldId` from `describe_workflows`.
+
+**NULL results for joined data:**
+- ActivityLink field is empty/null for some activities (expected with LEFT JOIN)
+- **The link field must have actual data populated.** A JOIN against a workflow where the ActivityLink field is unpopulated returns NULL on all joined columns regardless of ON-clause correctness. This is the most common false-negative — verify with `mcp__hailer__list_activities` that at least some activities have the link field set before concluding the JOIN syntax is wrong.
+
+---
+
+## Polymorphic Parent JOINs
+
+When an ActivityLink field can point to multiple workflows, LEFT JOIN both and COALESCE:
+
+```sql
+SELECT
+  b.nimi AS varaus,
+  COALESCE(e.nimi, v.nimi, '(ei linkitetty)') AS ylätaso,
+  COALESCE(e.pvm, v.pvm) AS pvm
+FROM b
+LEFT JOIN e ON b.tapahtuma = e.id
+LEFT JOIN v ON b.verkkovaraus = v.id
+```
+
+Each ActivityLink field gets its own source + JOIN. `COALESCE` picks the first non-null result — works because only one link is populated per activity.
+
+### Orphan Link Rows — Target Workflow Deleted or Unlisted
+
+If a target workflow is deleted or unlisted after activities were already linked to it, those link rows still exist in the source workflow but JOIN to that target returns nothing.
+
+**Diagnostic:**
+
+```sql
+SELECT
+  src.activityId,
+  src.link_field,
+  CASE
+    WHEN target1.id IS NOT NULL THEN 'target1'
+    WHEN target2.id IS NOT NULL THEN 'target2'
+    ELSE 'ORPHAN — target deleted/unlisted'
+  END AS link_status
+FROM src
+LEFT JOIN target1 ON src.link_field = target1.id
+LEFT JOIN target2 ON src.link_field = target2.id
+```
+
+### New Link Target Added — Audit All Name-Resolving Insights
+
+When a workflow is added as a new valid link target on an ActivityLink field, every insight that resolves that field's name via LEFT JOIN needs a parallel source + JOIN + COALESCE branch — otherwise rows linking to the new target return NULL silently.
+
+```javascript
+// Before: 3-target COALESCE
+COALESCE(a.name, b.name, c.name, '(ei linkitetty)') AS tuote
+
+// After: add proj source, JOIN, and COALESCE slot
+COALESCE(a.name, b.name, c.name, proj.name, '(ei linkitetty)') AS tuote
+```
+
+---
+
+## Human-Readable Output
+
+When an insight will be read by humans, JOIN every ActivityLink to its target and SELECT the name — not the link field itself.
+
+```sql
+-- ❌ Raw IDs — useless for humans
+SELECT t.task_name, t.project FROM t
+
+-- ✅ Human-readable
+SELECT t.task_name, p.project_name
+FROM t LEFT JOIN p ON t.project = p.id
+```
+
+Same for user fields:
+
+```sql
+SELECT t.task_name, u.name AS assignee
+FROM t LEFT JOIN user u ON u._id = t.assignee
+```
+
+---
+
+## ActivityLink Display Value — activityName vs a Specific Field
+
+**Option A — Show the linked activity's display name:** use `meta: 'name'` in the linked source's `fields[]`.
+
+**Option B — Show a specific field's value from the linked workflow:** add the field to the linked source's `fields[]` using `fieldId`.
+
+Ask which one is wanted before writing the JOIN — wrong choice means rewriting the source definitions.
+
+---
+
+## Date Bucketing — Prefer Underlying datetimerange Over Function Fields
+
+Function-field-derived date values can be null across large portions of a workflow — the computation may not have run. In SQL `null` in date math evaluates to `0`, which formats as `1970-01`. A few activities with valid values look fine in `run_insight` ad-hoc (up to 200 rows); the full pushed insight may be nearly all epoch values.
+
+**Prefer the underlying `datetimerange` field over a function-field derivative when bucketing dates.** The datetimerange field is always populated if the user entered a value.
+
+---
+
+## Field-Type JOIN Matrix
+
+| Source field type | JOIN needed? | Syntax / alternative |
+|---|---|---|
+| text, textarea | No | raw string |
+| number, numericunit | No | raw number |
+| date, datetime | No (format inline) | `strftime('%Y-%m-%d', field, 'unixepoch')` — custom fields are seconds. Meta `created`/`updated` are ms: `strftime('%Y-%m-%d', field/1000, 'unixepoch')`. |
+| dropdown | No — inline CASE | `CASE field WHEN 'key1' THEN 'Label 1' ... ELSE field END AS label` |
+| user (single) | Yes | `LEFT JOIN user u ON u._id = src.ownerField` → `u.name` |
+| activitylink (single target wf) | Yes — one JOIN | `LEFT JOIN targetwf t ON t.id = src.linkField` → `t.name` |
+| activitylink (multi target wf — polymorphic) | Yes — one JOIN per target, `COALESCE` | See polymorphic section above |
+| boolean | No (format inline) | `CASE WHEN field = true THEN 'Yes' ELSE 'No' END` |
+
+### User Field
+
+The `user` table is a pseudo-table — you don't declare it in `sources[]`, it's always joinable. Column names: `_id`, `name`. (`email`, `firstname`, `lastname` do not exist — error "no such column".)
+
+```sql
+SELECT d.name AS deal, COALESCE(u.name, 'Unassigned') AS owner
+FROM deals d
+LEFT JOIN user u ON u._id = d.owner
+```
+
+No multi-user field types in Hailer — every user field stores a scalar user ID.
+
+### Dropdown Label Display
+
+Dropdowns store the option key (e.g. `"saas"`), not the visible label (`"SaaS"`). Decode inline:
+
+```sql
+SELECT
+  a.name AS account,
+  CASE a.industry
+    WHEN 'saas'          THEN 'SaaS'
+    WHEN 'retail'        THEN 'Retail'
+    WHEN 'manufacturing' THEN 'Manufacturing'
+    ELSE 'Other'
+  END AS industry_label
+FROM accounts a
+```
+
+Default: inline CASE for 3–10 options, lookup table for more.
+
+### Phase Name Display
+
+**Do not use CASE on `phaseId` to map phase IDs to phase names.** The built-in `phaseName` column already contains the current phase's display name — just SELECT it directly.
+
+```sql
+-- Use this
+SELECT activityName, phaseName FROM src
+
+-- Do not do this — unnecessary and brittle
+SELECT activityName, CASE phaseId WHEN '64a1b2c3...' THEN 'New' ... END AS phase FROM src
+```
+
+---
+
+## One-to-Many Backlink JOINs — Row Multiplication Trap
+
+There are no multi-value field types in Hailer — every field holds a scalar. Row multiplication in insights comes from **one-to-many backlink JOINs**, where you join from the "one" side (a parent workflow) to the "many" side (child activities that link back to it).
+
+**Classic case:** `Accounts LEFT JOIN Deals ON deals.account_link = accounts.id` — one account, many deals → one row per deal, not per account. `SUM(account.revenue)` then doubles or triples.
+
+**Detection test:** compare `COUNT(*)` in the insight against the known activity count in the parent workflow. If `COUNT(*) > parent activity count`, you have row multiplication.
+
+### Fix Patterns
+
+**1. `COUNT(DISTINCT a._id)` — count unique parent activities, not rows**
+
+**2. Subquery pre-aggregation (safest):**
+
+```sql
+SELECT
+  a.account_name,
+  COALESCE(ds.deal_count, 0) AS deal_count,
+  COALESCE(ds.pipeline, 0) AS pipeline
+FROM accounts a
+LEFT JOIN (
+  SELECT d.account_link, COUNT(*) AS deal_count, SUM(d.amount) AS pipeline
+  FROM deals d
+  GROUP BY d.account_link
+) ds ON ds.account_link = a.id
+```
+
+**3. `GROUP_CONCAT(DISTINCT ...)` — roll child names into a single display string:**
+
+```sql
+SELECT
+  a.account_name,
+  COUNT(DISTINCT d.id) AS deal_count,
+  GROUP_CONCAT(DISTINCT d.deal_name) AS deal_names
+FROM accounts a
+LEFT JOIN deals d ON d.account_link = a.id
+GROUP BY a.id, a.account_name
+```
+
+---
+
+## 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 required)
+- [ ] If insight is for humans: ActivityLink fields resolve to names, not IDs
+- [ ] Tested with `mcp__hailer__run_insight` first