@hailer/mcp 0.0.1

package/.claude/skills/install-workflow-skill/SKILL.md

@@ -0,0 +1,1056 @@
+---
+name: Installing Hailer Workflows
+description: Complete guide for installing and designing Hailer workflows - use when creating database schemas or workflow structures
+---
+
+# Installing Hailer Workflows - Complete Guide
+
+Complete reference for designing, installing, and managing Hailer workflows using the `install_workflow` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Core Concepts](#core-concepts)
+4. [Field Types Reference](#field-types-reference)
+5. [ID Patterns and Naming](#id-patterns-and-naming)
+6. [Basic Examples](#basic-examples)
+7. [Advanced Patterns](#advanced-patterns)
+8. [Relationships Between Workflows](#relationships-between-workflows)
+9. [Best Practices](#best-practices)
+10. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**Basic Workflow Installation:**
+
+```javascript
+install_workflow({
+  workflowTemplates: [{
+    _id: '_0001',
+    name: 'Tasks',
+    fields: {
+      _1000: { label: 'Title', type: 'text', key: 'title', required: true },
+      _1001: { label: 'Priority', type: 'textpredefinedoptions', key: 'priority',
+               data: ['Low', 'Medium', 'High'] }
+    },
+    phases: {
+      _2000: { name: 'To Do', isInitial: true },
+      _2001: { name: 'Done' }
+    }
+  }]
+})
+```
+
+**Key Rules:**
+- ALL IDs follow pattern: underscore + 4 digits (`_0001`, `_1000`, `_2000`)
+- Workflow IDs: `_0001`, `_0002`, `_0003`, etc.
+- Field IDs: `_1000`, `_1001`, `_1002`, etc.
+- Phase IDs: `_2000`, `_2001`, `_2002`, etc.
+- 🚨 **CRITICAL:** Phase IDs MUST be unique across ALL workflows (e.g., Teams uses _2000, Players uses _2001-2004, Matches uses _2005-2007)
+- Always set `key` on fields for readable API responses
+- User must be workspace administrator
+
+## ❌ Common Mistakes (CRITICAL - READ THIS FIRST!)
+
+Based on actual API validation failures, avoid these mistakes:
+
+### 1. Wrong Property Names in Fields
+
+**❌ DON'T use `name` in field definitions:**
+```javascript
+fields: {
+  _1000: {
+    name: "task_name",      // ❌ WRONG - API rejects "name"
+    label: "Task Name",
+    type: "text"
+  }
+}
+```
+
+**✅ DO use only `label` and optionally `key`:**
+```javascript
+fields: {
+  _1000: {
+    label: "Task Name",     // ✅ CORRECT - Required
+    key: "taskName",        // ✅ CORRECT - Optional but recommended
+    type: "text"
+  }
+}
+```
+
+### 2. Wrong Property Names for Dropdown Options
+
+**❌ DON'T use `options`:**
+```javascript
+_1001: {
+  label: "Priority",
+  type: "textpredefinedoptions",
+  options: ["Low", "High"]    // ❌ WRONG - Use "data" not "options"
+}
+```
+
+**✅ DO use `data`:**
+```javascript
+_1001: {
+  label: "Priority",
+  type: "textpredefinedoptions",
+  data: ["Low", "High"]       // ✅ CORRECT
+}
+```
+
+### 3. Arrays Instead of Objects
+
+**❌ DON'T use arrays for fields and phases:**
+```javascript
+workflowTemplates: [{
+  fields: [                   // ❌ WRONG - Array
+    { _id: "_1000", label: "Title", type: "text" }
+  ],
+  phases: [                   // ❌ WRONG - Array
+    { _id: "_2000", name: "To Do" }
+  ]
+}]
+```
+
+**✅ DO use objects with IDs as keys:**
+```javascript
+workflowTemplates: [{
+  fields: {                   // ✅ CORRECT - Object
+    _1000: { label: "Title", type: "text" }
+  },
+  phases: {                   // ✅ CORRECT - Object
+    _2000: { name: "To Do", isInitial: true }
+  }
+}]
+```
+
+### 4. Missing Required Wrapper
+
+**❌ DON'T pass fields directly:**
+```javascript
+install_workflow({
+  name: "My Workflow",       // ❌ WRONG - Missing workflowTemplates wrapper
+  fields: {...}
+})
+```
+
+**✅ DO use `workflowTemplates` array:**
+```javascript
+install_workflow({
+  workflowTemplates: [{       // ✅ CORRECT - Required wrapper
+    name: "My Workflow",
+    fields: {...}
+  }]
+})
+```
+
+### 5. Field Property Summary
+
+**Only these properties are allowed in field definitions:**
+- ✅ `label` (required) - Display name
+- ✅ `type` (required) - Field type (text, date, etc.)
+- ✅ `key` (optional but recommended) - API key name
+- ✅ `data` (for activitylink, textpredefinedoptions) - Options or links
+- ✅ `required` (optional) - Boolean for required fields
+- ✅ `placeholder` (optional) - Placeholder text
+- ✅ `unit` (for numeric/text with units) - Unit string
+- ❌ `name` - NOT ALLOWED (API will reject)
+- ❌ `options` - NOT ALLOWED (use `data` instead)
+
+### 6. 🚨 CRITICAL: Phase IDs Must Be Unique Across ALL Workflows
+
+**⚠️ THIS IS THE #1 CAUSE OF DATA CORRUPTION ⚠️**
+
+When installing multiple workflows in a single call, **each workflow MUST use unique phase IDs**. Reusing phase IDs across workflows causes them to **share the same phases**, resulting in activities appearing in multiple workflows.
+
+**❌ WRONG - Workflows share phase IDs (causes data corruption):**
+```javascript
+install_workflow({
+  workflowTemplates: [
+    {
+      _id: '_0001',
+      name: 'Teams',
+      phases: {
+        _2000: { name: 'Active', isInitial: true }  // ❌ Uses _2000
+      }
+    },
+    {
+      _id: '_0002',
+      name: 'Players',
+      phases: {
+        _2000: { name: 'Active Squad', isInitial: true }  // ❌ REUSES _2000!
+      }
+    }
+  ]
+})
+```
+
+**Result:** Both workflows share phase `_2000` → Activities created in Teams appear in Players and vice versa!
+
+**✅ CORRECT - Each workflow has unique phase IDs:**
+```javascript
+install_workflow({
+  workflowTemplates: [
+    {
+      _id: '_0001',
+      name: 'Teams',
+      phases: {
+        _2000: { name: 'Active', isInitial: true }  // ✅ Teams: _2000
+      }
+    },
+    {
+      _id: '_0002',
+      name: 'Players',
+      phases: {
+        _2001: { name: 'Active Squad', isInitial: true },  // ✅ Players: _2001-2004
+        _2002: { name: 'On Loan' },
+        _2003: { name: 'Injured' },
+        _2004: { name: 'Inactive' }
+      }
+    },
+    {
+      _id: '_0003',
+      name: 'Matches',
+      phases: {
+        _2005: { name: 'Scheduled', isInitial: true },  // ✅ Matches: _2005-2007
+        _2006: { name: 'Completed' },
+        _2007: { name: 'Cancelled' }
+      }
+    }
+  ]
+})
+```
+
+**Phase ID Allocation Strategy:**
+- Workflow 1: `_2000` - `_2009` (reserve 10 IDs)
+- Workflow 2: `_2010` - `_2019` (reserve 10 IDs)
+- Workflow 3: `_2020` - `_2029` (reserve 10 IDs)
+- etc.
+
+**Why this happens:**
+- Template phase IDs (_2000, _2001, etc.) are used to generate real phase IDs
+- If two workflows use the same template phase ID, the API creates ONE real phase ID
+- Both workflows then reference the same physical phase in the database
+- Activities in that phase appear in BOTH workflows
+
+**How to detect:**
+```javascript
+// If two workflows return the same phase ID, they're sharing phases!
+list_workflow_phases({ workflowId: 'teams-id' })    // Returns: _2000 → 691f2e1aec05d1dc1dafbee6
+list_workflow_phases({ workflowId: 'players-id' })  // Returns: _2000 → 691f2e1aec05d1dc1dafbee6  ❌ SAME ID!
+```
+
+**How to fix:**
+1. Remove corrupted workflows: `remove_workflow({ workflowId: 'xxx' })`
+2. Reinstall with unique phase IDs as shown above
+3. Verify with `list_workflow_phases` for each workflow
+
+## Overview
+
+**Think of workflows as database tables:**
+- **Workflows** = Database tables
+- **Fields** = Columns
+- **Activities** = Rows
+- **ActivityLinks** = Foreign keys
+- **Phases** = Status/state columns
+
+Workflows define the structure for your data in Hailer. Once installed, you can create activities (records) within these workflows using the `create_activity` tool.
+
+## Core Concepts
+
+### Workflow Structure
+
+A workflow consists of:
+
+1. **Workflow Definition**: Name, description, and template ID
+2. **Fields**: Define what data each activity can hold
+3. **Phases**: Define the lifecycle states of activities
+4. **Field Order**: Controls display order (auto-generated if omitted)
+5. **Phase Order**: Controls phase sequence (auto-generated if omitted)
+
+### Template IDs vs Real IDs
+
+When you install workflows, you use **template IDs** (like `_0001`, `_1000`) to reference workflows and fields. The API returns **real IDs** (like `68446dc05b30685f67c6fcd4`) which you use for subsequent operations.
+
+**Example mapping:**
+```json
+{
+  "_0001": "68446dc05b30685f67c6fcd4",  // Workflow ID
+  "_1000": "6901ebb64fd57ff171f43338",  // Field ID
+  "_1001": "6901ebb64fd57ff171f43339"   // Field ID
+}
+```
+
+Use real IDs when:
+- Creating activities: `create_activity({ workflowId: "68446dc05b30685f67c6fcd4", ... })`
+- Listing activities: `list_activities({ workflowId: "68446dc05b30685f67c6fcd4" })`
+- Setting field values: `fields: { "6901ebb64fd57ff171f43338": "value" }`
+
+### The `key` Field
+
+The `key` field provides readable names for fields in API responses when using `returnFlat: true`:
+
+**Without key:**
+```javascript
+fields: {
+  "6901ebb64fd57ff171f43338": "My Task Title",
+  "6901ebb64fd57ff171f43339": "High"
+}
+```
+
+**With key:**
+```javascript
+fields: {
+  "title": "My Task Title",
+  "priority": "High"
+}
+```
+
+**Always set keys** for better API ergonomics.
+
+## Field Types Reference
+
+### Text Fields
+
+**text** - Single-line text input
+```javascript
+{ label: 'Title', type: 'text', key: 'title', required: true }
+```
+
+**textarea** - Multi-line text input
+```javascript
+{ label: 'Description', type: 'textarea', key: 'description' }
+```
+
+**textunit** - Text with unit (e.g., "5 kg", "10 meters")
+```javascript
+{ label: 'Weight', type: 'textunit', key: 'weight', unit: 'kg' }
+```
+
+**textpredefinedoptions** - Dropdown/select with predefined options
+```javascript
+{
+  label: 'Priority',
+  type: 'textpredefinedoptions',
+  key: 'priority',
+  data: ['Low', 'Medium', 'High']
+}
+```
+
+### Numeric Fields
+
+**numeric** - Number input
+```javascript
+{ label: 'Quantity', type: 'numeric', key: 'quantity' }
+```
+
+**numericunit** - Number with unit
+```javascript
+{ label: 'Distance', type: 'numericunit', key: 'distance', unit: 'km' }
+```
+
+### Date/Time Fields
+
+**date** - Date picker
+```javascript
+{ label: 'Due Date', type: 'date', key: 'dueDate' }
+```
+
+**time** - Time picker
+```javascript
+{ label: 'Start Time', type: 'time', key: 'startTime' }
+```
+
+**datetime** - Date and time picker
+```javascript
+{ label: 'Created At', type: 'datetime', key: 'createdAt' }
+```
+
+**daterange** - Start and end dates
+```javascript
+{ label: 'Project Duration', type: 'daterange', key: 'duration' }
+```
+
+**timerange** - Start and end times
+```javascript
+{ label: 'Working Hours', type: 'timerange', key: 'hours' }
+```
+
+**datetimerange** - Start and end date/times
+```javascript
+{ label: 'Event Period', type: 'datetimerange', key: 'eventPeriod' }
+```
+
+### Relation Fields
+
+**activitylink** - Link to other workflow activities (foreign key)
+```javascript
+{
+  label: 'Project',
+  type: 'activitylink',
+  key: 'project',
+  data: ['_0001']  // Links to workflow _0001
+}
+```
+
+**teams** - Select team from workspace
+```javascript
+{ label: 'Owner Team', type: 'teams', key: 'ownerTeam' }
+```
+
+**users** - Select user from workspace
+```javascript
+{ label: 'Assigned To', type: 'users', key: 'assignedTo' }
+```
+
+### Layout Fields
+
+**subheader** - Group fields into collapsible sections
+```javascript
+{ label: 'Contact Information', type: 'subheader' }
+```
+
+### Other Fields
+
+**country** - Country selector
+```javascript
+{ label: 'Country', type: 'country', key: 'country' }
+```
+
+## ID Patterns and Naming
+
+### Pattern Rules
+
+All IDs must follow: **underscore + 4 digits**
+
+**Workflow IDs:**
+- Start from `_0001`
+- Increment: `_0002`, `_0003`, etc.
+- Used in activitylink `data` field to reference workflows
+
+**Field IDs:**
+- Start from `_1000`
+- Increment: `_1001`, `_1002`, etc.
+- No gaps required - can skip numbers
+
+**Phase IDs:**
+- Start from `_2000`
+- Increment: `_2001`, `_2002`, etc.
+- At least one phase with `isInitial: true` required
+
+### Key Naming Conventions
+
+Use camelCase for keys:
+- `title`, `description`, `projectName`
+- `startDate`, `endDate`, `dueDate`
+- `assignedTo`, `ownedBy`, `relatedTo`
+- `priority`, `status`, `category`
+
+## Basic Examples
+
+### Example 1: Simple Task List
+
+```javascript
+install_workflow({
+  workflowTemplates: [{
+    _id: '_0001',
+    name: 'Tasks',
+    description: 'Simple task tracking',
+    fields: {
+      _1000: {
+        label: 'Title',
+        type: 'text',
+        key: 'title',
+        required: true,
+        placeholder: 'Enter task title'
+      },
+      _1001: {
+        label: 'Priority',
+        type: 'textpredefinedoptions',
+        key: 'priority',
+        data: ['Low', 'Medium', 'High']
+      },
+      _1002: {
+        label: 'Due Date',
+        type: 'date',
+        key: 'dueDate'
+      },
+      _1003: {
+        label: 'Description',
+        type: 'textarea',
+        key: 'description'
+      }
+    },
+    phases: {
+      _2000: { name: 'To Do', isInitial: true },
+      _2001: { name: 'In Progress' },
+      _2002: { name: 'Done' }
+    }
+  }]
+})
+```
+
+### Example 2: Customer Database
+
+```javascript
+install_workflow({
+  workflowTemplates: [{
+    _id: '_0001',
+    name: 'Customers',
+    fields: {
+      _1000: { label: 'Company Name', type: 'text', key: 'companyName', required: true },
+      _1001: { label: 'Contact Person', type: 'text', key: 'contactPerson' },
+      _1002: { label: 'Email', type: 'text', key: 'email' },
+      _1003: { label: 'Phone', type: 'text', key: 'phone' },
+      _1004: { label: 'Country', type: 'country', key: 'country' },
+      _1005: { label: 'Status', type: 'textpredefinedoptions', key: 'status',
+               data: ['Lead', 'Active', 'Inactive'] }
+    },
+    phases: {
+      _2000: { name: 'Active', isInitial: true }
+    }
+  }]
+})
+```
+
+### Example 3: Using Subheaders for Organization
+
+```javascript
+install_workflow({
+  workflowTemplates: [{
+    _id: '_0001',
+    name: 'Contacts',
+    fields: {
+      // Basic Info Section
+      _1000: { label: 'Basic Information', type: 'subheader' },
+      _1001: { label: 'Full Name', type: 'text', key: 'fullName', required: true },
+      _1002: { label: 'Company', type: 'text', key: 'company' },
+      _1003: { label: 'Position', type: 'text', key: 'position' },
+
+      // Contact Details Section
+      _1004: { label: 'Contact Details', type: 'subheader' },
+      _1005: { label: 'Email', type: 'text', key: 'email' },
+      _1006: { label: 'Phone', type: 'text', key: 'phone' },
+
+      // Address Section
+      _1007: { label: 'Address', type: 'subheader' },
+      _1008: { label: 'Street', type: 'text', key: 'street' },
+      _1009: { label: 'City', type: 'text', key: 'city' },
+      _1010: { label: 'Country', type: 'country', key: 'country' }
+    },
+    phases: {
+      _2000: { name: 'Active', isInitial: true }
+    }
+  }]
+})
+```
+
+## Advanced Patterns
+
+### Date Range Tracking
+
+```javascript
+{
+  workflowTemplates: [{
+    _id: '_0001',
+    name: 'Projects',
+    fields: {
+      _1000: { label: 'Project Name', type: 'text', key: 'projectName', required: true },
+      _1001: { label: 'Duration', type: 'daterange', key: 'duration' },
+      _1002: { label: 'Budget', type: 'numericunit', key: 'budget', unit: 'USD' },
+      _1003: { label: 'Status', type: 'textpredefinedoptions', key: 'status',
+               data: ['Planning', 'Active', 'On Hold', 'Completed'] }
+    },
+    phases: {
+      _2000: { name: 'Planning', isInitial: true },
+      _2001: { name: 'Execution' },
+      _2002: { name: 'Completed' }
+    }
+  }]
+}
+```
+
+### Multiple Predefined Options
+
+```javascript
+{
+  workflowTemplates: [{
+    _id: '_0001',
+    name: 'Support Tickets',
+    fields: {
+      _1000: { label: 'Title', type: 'text', key: 'title', required: true },
+      _1001: { label: 'Priority', type: 'textpredefinedoptions', key: 'priority',
+               data: ['Low', 'Normal', 'High', 'Urgent'] },
+      _1002: { label: 'Category', type: 'textpredefinedoptions', key: 'category',
+               data: ['Technical', 'Billing', 'General', 'Bug Report'] },
+      _1003: { label: 'Assigned To', type: 'users', key: 'assignedTo' },
+      _1004: { label: 'Description', type: 'textarea', key: 'description' }
+    },
+    phases: {
+      _2000: { name: 'Open', isInitial: true },
+      _2001: { name: 'In Progress' },
+      _2002: { name: 'Resolved' },
+      _2003: { name: 'Closed' }
+    }
+  }]
+}
+```
+
+## Relationships Between Workflows
+
+### One-to-Many: Projects and Tasks
+
+```javascript
+install_workflow({
+  workflowTemplates: [
+    // Parent workflow: Projects
+    {
+      _id: '_0001',
+      name: 'Projects',
+      fields: {
+        _1000: { label: 'Project Name', type: 'text', key: 'projectName', required: true },
+        _1001: { label: 'Start Date', type: 'date', key: 'startDate' },
+        _1002: { label: 'Budget', type: 'numericunit', key: 'budget', unit: 'USD' }
+      },
+      phases: {
+        _2000: { name: 'Active', isInitial: true }
+      }
+    },
+
+    // Child workflow: Tasks (links to Projects)
+    {
+      _id: '_0002',
+      name: 'Tasks',
+      fields: {
+        _1000: { label: 'Task Title', type: 'text', key: 'title', required: true },
+        _1001: {
+          label: 'Project',
+          type: 'activitylink',
+          key: 'project',
+          data: ['_0001']  // Links to Projects workflow
+        },
+        _1002: { label: 'Due Date', type: 'date', key: 'dueDate' },
+        _1003: { label: 'Assigned To', type: 'users', key: 'assignedTo' }
+      },
+      phases: {
+        _2001: { name: 'To Do', isInitial: true },     // ✅ Unique phase IDs (_2001-2003)
+        _2002: { name: 'In Progress' },
+        _2003: { name: 'Done' }
+      }
+    }
+  ]
+})
+```
+
+**Usage after installation:**
+```javascript
+// 1. Get real IDs from installation response
+// {
+//   "_0001": "project-workflow-real-id",
+//   "_0002": "task-workflow-real-id",
+//   "_1001": "project-link-field-real-id"
+// }
+
+// 2. Create a project
+create_activity({
+  workflowId: "project-workflow-real-id",
+  name: "Website Redesign",
+  fields: { "projectName": "Website Redesign", "budget": "50000" }
+})
+// Returns: { _id: "project-activity-id", ... }
+
+// 3. Create tasks linked to project
+create_activity({
+  workflowId: "task-workflow-real-id",
+  name: "Design mockups",
+  fields: {
+    "title": "Design mockups",
+    "project": "project-activity-id",  // Link to project activity
+    "dueDate": "2024-12-31"
+  }
+})
+```
+
+### Three-Level Hierarchy: Projects → Topics → Tasks
+
+```javascript
+install_workflow({
+  workflowTemplates: [
+    // Level 1: Projects
+    {
+      _id: '_0001',
+      name: 'Projects',
+      fields: {
+        _1000: { label: 'Project Name', type: 'text', key: 'projectName', required: true },
+        _1001: { label: 'Description', type: 'textarea', key: 'description' }
+      },
+      phases: {
+        _2000: { name: 'Active', isInitial: true }
+      }
+    },
+
+    // Level 2: Topics (links to Projects)
+    {
+      _id: '_0002',
+      name: 'Topics',
+      fields: {
+        _1000: { label: 'Topic Name', type: 'text', key: 'topicName', required: true },
+        _1001: {
+          label: 'Project',
+          type: 'activitylink',
+          key: 'project',
+          data: ['_0001']
+        }
+      },
+      phases: {
+        _2001: { name: 'Active', isInitial: true }  // ✅ Unique phase ID (_2001)
+      }
+    },
+
+    // Level 3: Tasks (links to Topics)
+    {
+      _id: '_0003',
+      name: 'Tasks',
+      fields: {
+        _1000: { label: 'Task Title', type: 'text', key: 'title', required: true },
+        _1001: {
+          label: 'Topic',
+          type: 'activitylink',
+          key: 'topic',
+          data: ['_0002']
+        },
+        _1002: { label: 'Priority', type: 'textpredefinedoptions', key: 'priority',
+                 data: ['Low', 'Medium', 'High'] }
+      },
+      phases: {
+        _2002: { name: 'To Do', isInitial: true },  // ✅ Unique phase IDs (_2002-2003)
+        _2003: { name: 'Done' }
+      }
+    }
+  ]
+})
+```
+
+### Many-to-Many: Using Multiple ActivityLinks
+
+```javascript
+{
+  workflowTemplates: [{
+    _id: '_0003',
+    name: 'Tasks',
+    fields: {
+      _1000: { label: 'Task Title', type: 'text', key: 'title', required: true },
+      _1001: {
+        label: 'Related Items',
+        type: 'activitylink',
+        key: 'relatedItems',
+        data: ['_0001', '_0002']  // Can link to Projects OR Topics
+      }
+    },
+    phases: {
+      _2004: { name: 'To Do', isInitial: true }  // ✅ Use _2004+ (assuming _0001, _0002 used _2000-2003)
+    }
+  }]
+}
+```
+
+## Best Practices
+
+### 1. Always Use Keys
+
+**Bad:**
+```javascript
+fields: {
+  _1000: { label: 'Customer Name', type: 'text' }  // No key
+}
+```
+
+**Good:**
+```javascript
+fields: {
+  _1000: { label: 'Customer Name', type: 'text', key: 'customerName' }
+}
+```
+
+### 2. Use Descriptive Names
+
+**Bad:**
+```javascript
+{ label: 'Name', type: 'text', key: 'name' }  // Ambiguous
+```
+
+**Good:**
+```javascript
+{ label: 'Customer Name', type: 'text', key: 'customerName' }  // Clear
+{ label: 'Project Name', type: 'text', key: 'projectName' }  // Clear
+```
+
+### 3. Set Required Fields Appropriately
+
+```javascript
+fields: {
+  _1000: { label: 'Title', type: 'text', key: 'title', required: true },  // Essential
+  _1001: { label: 'Description', type: 'textarea', key: 'description' }    // Optional
+}
+```
+
+### 4. Use Subheaders for Long Forms
+
+For workflows with many fields (>5), organize with subheaders:
+
+```javascript
+fields: {
+  _1000: { label: 'Basic Info', type: 'subheader' },
+  _1001: { label: 'Name', type: 'text', key: 'name' },
+  _1002: { label: 'Email', type: 'text', key: 'email' },
+
+  _1003: { label: 'Additional Details', type: 'subheader' },
+  _1004: { label: 'Notes', type: 'textarea', key: 'notes' }
+}
+```
+
+### 5. Choose Appropriate Field Types
+
+**For limited options:** Use `textpredefinedoptions`
+```javascript
+{ label: 'Status', type: 'textpredefinedoptions', key: 'status',
+  data: ['Draft', 'Review', 'Published'] }
+```
+
+**For measurements:** Use numeric fields with units
+```javascript
+{ label: 'Weight', type: 'numericunit', key: 'weight', unit: 'kg' }
+```
+
+**For relationships:** Use activitylink with clear labels
+```javascript
+{ label: 'Parent Project', type: 'activitylink', key: 'parentProject', data: ['_0001'] }
+```
+
+### 6. Phase Design
+
+**Minimum viable:**
+```javascript
+phases: {
+  _2000: { name: 'Active', isInitial: true }
+}
+```
+
+**Status workflow:**
+```javascript
+phases: {
+  _2000: { name: 'To Do', isInitial: true },
+  _2001: { name: 'In Progress' },
+  _2002: { name: 'Done' }
+}
+```
+
+**Approval workflow:**
+```javascript
+phases: {
+  _2000: { name: 'Draft', isInitial: true },
+  _2001: { name: 'Pending Review' },
+  _2002: { name: 'Approved' },
+  _2003: { name: 'Rejected' }
+}
+```
+
+### 7. Install Related Workflows Together
+
+When workflows reference each other via activitylink, install them in a single call:
+
+**Good:**
+```javascript
+install_workflow({
+  workflowTemplates: [
+    { _id: '_0001', name: 'Projects', ... },
+    { _id: '_0002', name: 'Tasks', fields: {
+      _1001: { type: 'activitylink', data: ['_0001'] }  // References _0001
+    }}
+  ]
+})
+```
+
+**Bad:**
+```javascript
+// First call
+install_workflow({ workflowTemplates: [{ _id: '_0001', name: 'Projects' }] })
+// Second call - must use real ID from first call
+install_workflow({ workflowTemplates: [{ _id: '_0002', name: 'Tasks',
+  fields: { _1001: { type: 'activitylink', data: ['real-id-from-first-call'] }}}]})
+```
+
+## Troubleshooting
+
+### Error: "Permission Denied"
+
+**Problem:** User must be workspace administrator.
+
+**Solution:**
+- Contact workspace admin to grant permissions
+- Verify you're logged in with correct account
+- Check `get_current_workspace` to confirm permissions
+
+### Error: "Workflow _id must match pattern _0001"
+
+**Problem:** Invalid workflow ID format.
+
+**Solution:**
+- Use pattern: `_0001`, `_0002`, `_0003` (underscore + 4 digits)
+- Must start with underscore
+- Must be exactly 4 digits
+
+### Error: "Field IDs must match pattern _1000"
+
+**Problem:** Invalid field ID format.
+
+**Solution:**
+- Use pattern: `_1000`, `_1001`, `_1002` (underscore + 4 digits)
+- Start from `_1000` or higher
+- Can skip numbers (e.g., `_1000`, `_1005`, `_1010`)
+
+### Error: "Phase IDs must match pattern _2000"
+
+**Problem:** Invalid phase ID format.
+
+**Solution:**
+- Use pattern: `_2000`, `_2001`, `_2002` (underscore + 4 digits)
+- Start from `_2000` or higher
+
+### Error: "At least one phase with isInitial: true required"
+
+**Problem:** No initial phase defined.
+
+**Solution:**
+```javascript
+phases: {
+  _2000: { name: 'Active', isInitial: true }  // Must have isInitial: true
+}
+```
+
+### Installation Succeeds But Can't Find Workflow
+
+**Problem:** Need to use real IDs, not template IDs.
+
+**Solution:**
+1. Installation returns mapping:
+   ```json
+   { "_0001": "68446dc05b30685f67c6fcd4" }
+   ```
+2. Use real ID in subsequent calls:
+   ```javascript
+   list_activities({ workflowId: "68446dc05b30685f67c6fcd4" })
+   ```
+
+### ActivityLink Not Working
+
+**Problem:** Wrong workflow ID in `data` field.
+
+**Solution:**
+
+**During installation** (use template ID):
+```javascript
+{
+  _id: '_0002',
+  fields: {
+    _1001: { type: 'activitylink', data: ['_0001'] }  // Template ID
+  }
+}
+```
+
+**After installation** (when updating field):
+```javascript
+update_workflow_field({
+  workflowId: "real-workflow-id",
+  fieldId: "real-field-id",
+  fieldData: {
+    data: ["target-real-workflow-id"]  // Real ID
+  }
+})
+```
+
+### Fields Not Showing in Expected Order
+
+**Problem:** Field order not specified.
+
+**Solution:**
+```javascript
+{
+  fields: { _1000: {...}, _1005: {...}, _1002: {...} },
+  fieldsOrder: ['_1000', '_1002', '_1005']  // Explicit order
+}
+```
+
+### Can't Create Activities in Phase
+
+**Problem:** Phase doesn't have `isInitial: true`.
+
+**Solution:** At least one phase must have `isInitial: true`. Activities can only be created in initial phases:
+```javascript
+phases: {
+  _2000: { name: 'New', isInitial: true },  // Can create activities here
+  _2001: { name: 'Done' }                    // Can't create, only move here
+}
+```
+
+## Integration with Other Tools
+
+### After Installation: Create Activities
+
+```javascript
+// 1. Install workflow
+const result = install_workflow({...});
+// Returns: { "_0001": "workflow-real-id", "_1000": "field-real-id" }
+
+// 2. Create activity
+create_activity({
+  workflowId: "workflow-real-id",
+  name: "Activity Name",
+  fields: {
+    "field-real-id": "value"
+  }
+})
+```
+
+### Use with Insights
+
+After installing workflows, create insights (SQL reports) over the data:
+
+```javascript
+create_insight({
+  name: 'Task Report',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'workflow-real-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'dueDate', fieldId: 'field-real-id' }
+    ]
+  }],
+  query: 'SELECT title, dueDate FROM tasks WHERE dueDate > "2024-01-01"'
+})
+```
+
+### Update Fields Later
+
+Use `update_workflow_field` to modify field properties after installation:
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-real-id",
+  fieldId: "field-real-id",
+  fieldData: {
+    label: "New Label",
+    key: "newKey",
+    data: ["updated-options"]
+  }
+})
+```
+
+## Additional Resources
+
+- Use `list_workflows` to view installed workflows
+- Use `get_workflow_schema` to inspect workflow structure
+- Use `list_workflow_phases` to view available phases
+- See `hailer-api` skill for comprehensive API documentation
+- See `mcp-tools` skill for implementation patterns