@hailer/mcp 0.0.1

package/.claude/skills/update-workflow-field-skill/SKILL.md

@@ -0,0 +1,1098 @@
+---
+name: Updating Workflow Fields
+description: Complete guide for modifying Hailer workflow fields - use when updating field properties, keys, or configurations
+---
+
+# Updating Workflow Fields - Complete Guide
+
+Complete reference for modifying workflow field properties using the `update_workflow_field` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Core Concepts](#core-concepts)
+4. [Auto-Generated Keys](#auto-generated-keys)
+5. [Common Use Cases](#common-use-cases)
+6. [Field Properties Reference](#field-properties-reference)
+7. [Advanced Updates](#advanced-updates)
+8. [Multi-Field Updates](#multi-field-updates)
+9. [Best Practices](#best-practices)
+10. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**Basic Field Update:**
+
+```javascript
+update_workflow_field({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  fieldId: "6901ebb64fd57ff171f43338",
+  fieldData: {
+    label: "Task Title",
+    key: "taskTitle"
+  }
+})
+```
+
+**Auto-Generate Key from Label:**
+
+```javascript
+update_workflow_field({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  fieldId: "6901ebb64fd57ff171f43338",
+  fieldData: {
+    label: "Start Date"
+    // key will auto-generate as "startDate"
+  }
+})
+```
+
+**Update ActivityLink Targets:**
+
+```javascript
+update_workflow_field({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  fieldId: "6901ebb64fd57ff171f43339",
+  fieldData: {
+    data: ["target-workflow-id-1", "target-workflow-id-2"]
+  }
+})
+```
+
+**Key Features:**
+- Auto-generates camelCase keys from labels
+- Updates any field property
+- Requires workspace administrator rights
+- Non-destructive (doesn't affect existing activity data)
+
+## Overview
+
+The `update_workflow_field` tool allows you to modify properties of existing fields in Hailer workflows. Unlike removing and recreating workflows, this tool lets you update field configurations without losing data.
+
+**Think of it as:**
+- ALTER TABLE in SQL (modifying column properties)
+- Schema migration without data loss
+- Field configuration updates
+- Metadata changes
+
+**Common Uses:**
+- Add readable keys to fields for better API responses
+- Update field labels for clarity
+- Modify ActivityLink targets
+- Change predefined options in dropdowns
+- Update field descriptions and placeholders
+- Change field requirements (required/optional)
+- Update field editability
+
+**What it Does NOT Do:**
+- Does not change existing activity field values
+- Does not delete field data
+- Does not change field type (type changes may be restricted)
+- Does not reorder fields (use workflow update for that)
+
+## Core Concepts
+
+### Field IDs vs Keys
+
+**Field ID:**
+- Permanent identifier: `6901ebb64fd57ff171f43338`
+- Generated by Hailer when field created
+- Never changes
+- Used in update_workflow_field tool
+
+**Field Key:**
+- Readable name: `taskTitle`, `startDate`, `priority`
+- Optional but recommended
+- Used in API responses with `returnFlat: true`
+- Can be added or changed with this tool
+
+### Field Properties
+
+**Updatable Properties:**
+- `label` - Display name in UI
+- `key` - Readable field name for API
+- `description` - Field help text
+- `placeholder` - Input placeholder text
+- `data` - For ActivityLink targets or predefined options
+- `required` - Whether field must be filled
+- `editable` - Whether field can be edited
+- `unit` - Unit for numeric/text unit fields
+
+**Properties That May Be Restricted:**
+- `type` - Field type (text, numeric, activitylink, etc.)
+  - Type changes may not be allowed or may cause issues
+  - Best practice: Don't change type after creation
+
+### Language Support
+
+Updates support multiple languages:
+- Default language: `en` (English)
+- Can specify language: `fi`, `sv`, `de`, etc.
+- Each language can have different labels/descriptions
+
+## Auto-Generated Keys
+
+The tool automatically generates camelCase keys from field labels if no key is provided.
+
+### Auto-Generation Rules
+
+**Pattern:** First word lowercase, subsequent words capitalized
+**Non-word characters removed:** Spaces, punctuation, special chars
+
+### Examples
+
+| Label | Auto-Generated Key |
+|-------|-------------------|
+| Start Date | startDate |
+| Due Date | dueDate |
+| Related To | relatedTo |
+| Project Name | projectName |
+| Owner Team | ownerTeam |
+| Priority Level | priorityLevel |
+| Customer Contact | customerContact |
+| Is Active | isActive |
+| Total Amount | totalAmount |
+| Start Date & Time | startDateTime |
+
+### Custom Keys
+
+You can override auto-generation by providing explicit key:
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Customer Name",
+    key: "custName"  // Custom key instead of auto-generated "customerName"
+  }
+})
+```
+
+### Disabling Auto-Generation
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "New Label"
+  },
+  autoGenerateKey: false  // Don't auto-generate key
+})
+```
+
+## Common Use Cases
+
+### Use Case 1: Add Keys to Existing Fields
+
+**Situation:** Workflow created without keys, want readable API responses.
+
+**Solution:**
+
+```javascript
+// 1. Get workflow schema to see fields
+const schema = get_workflow_schema({
+  workflowId: "68446dc05b30685f67c6fcd4"
+})
+
+// 2. Add key to each field (auto-generated from labels)
+update_workflow_field({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  fieldId: "field-id-1",
+  fieldData: {
+    label: "Task Title"  // Key auto-generates as "taskTitle"
+  }
+})
+
+update_workflow_field({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  fieldId: "field-id-2",
+  fieldData: {
+    label: "Due Date"  // Key auto-generates as "dueDate"
+  }
+})
+
+// 3. Now use with returnFlat for readable responses
+list_activities({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  returnFlat: true
+})
+// Returns: { taskTitle: "My Task", dueDate: "2024-12-31" }
+```
+
+### Use Case 2: Update ActivityLink Targets
+
+**Situation:** Need to change which workflows a field links to.
+
+**Solution:**
+
+```javascript
+// Current: Field links to one workflow
+// Want: Field links to two workflows
+
+update_workflow_field({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  fieldId: "link-field-id",
+  fieldData: {
+    data: [
+      "target-workflow-id-1",
+      "target-workflow-id-2"
+    ]
+  }
+})
+```
+
+**Example - Link Tasks to Projects or Topics:**
+
+```javascript
+// Before: Tasks link only to Projects
+// After: Tasks can link to Projects OR Topics
+
+update_workflow_field({
+  workflowId: "tasks-workflow-id",
+  fieldId: "related-to-field-id",
+  fieldData: {
+    label: "Related To",
+    key: "relatedTo",
+    data: [
+      "projects-workflow-id",
+      "topics-workflow-id"
+    ]
+  }
+})
+```
+
+### Use Case 3: Update Predefined Options
+
+**Situation:** Need to add/change dropdown options.
+
+**Solution:**
+
+```javascript
+// Before: Priority has ["Low", "Medium", "High"]
+// After: Add "Urgent" option
+
+update_workflow_field({
+  workflowId: "68446dc05b30685f67c6fcd4",
+  fieldId: "priority-field-id",
+  fieldData: {
+    data: ["Low", "Medium", "High", "Urgent"]
+  }
+})
+```
+
+**Example - Update Status Options:**
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "status-field-id",
+  fieldData: {
+    label: "Status",
+    key: "status",
+    data: [
+      "Not Started",
+      "In Progress",
+      "Blocked",
+      "Review",
+      "Done"
+    ]
+  }
+})
+```
+
+### Use Case 4: Change Field Labels
+
+**Situation:** Improve clarity of field names.
+
+**Solution:**
+
+```javascript
+// Before: "Name" (ambiguous)
+// After: "Customer Name" (clear)
+
+update_workflow_field({
+  workflowId: "customers-workflow-id",
+  fieldId: "name-field-id",
+  fieldData: {
+    label: "Customer Name",
+    key: "customerName"
+  }
+})
+```
+
+### Use Case 5: Add Descriptions and Placeholders
+
+**Situation:** Help users understand field purpose.
+
+**Solution:**
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "email-field-id",
+  fieldData: {
+    label: "Email Address",
+    key: "email",
+    description: "Primary contact email for this customer",
+    placeholder: "user@example.com"
+  }
+})
+```
+
+### Use Case 6: Make Field Required/Optional
+
+**Situation:** Change validation requirements.
+
+**Solution:**
+
+```javascript
+// Make field required
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    required: true
+  }
+})
+
+// Make field optional
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    required: false
+  }
+})
+```
+
+### Use Case 7: Update Field Editability
+
+**Situation:** Control whether field can be edited after creation.
+
+**Solution:**
+
+```javascript
+// Make field read-only
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "created-date-field-id",
+  fieldData: {
+    editable: false
+  }
+})
+
+// Make field editable
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "status-field-id",
+  fieldData: {
+    editable: true
+  }
+})
+```
+
+## Field Properties Reference
+
+### Text Field Properties
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Customer Name",
+    key: "customerName",
+    description: "Full legal name of the customer",
+    placeholder: "Enter customer name",
+    required: true,
+    editable: true
+  }
+})
+```
+
+### Text with Predefined Options
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Priority",
+    key: "priority",
+    description: "Task priority level",
+    data: ["Low", "Medium", "High", "Urgent"],  // Options
+    required: true
+  }
+})
+```
+
+### Numeric Field Properties
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Quantity",
+    key: "quantity",
+    description: "Number of items",
+    placeholder: "0",
+    required: false
+  }
+})
+```
+
+### Numeric with Unit
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Weight",
+    key: "weight",
+    unit: "kg",  // Unit
+    description: "Package weight in kilograms"
+  }
+})
+```
+
+### ActivityLink Properties
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Related Project",
+    key: "relatedProject",
+    description: "Link to parent project",
+    data: [
+      "projects-workflow-id",
+      "topics-workflow-id"
+    ],  // Target workflows
+    required: false
+  }
+})
+```
+
+### Date/DateTime Properties
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Due Date",
+    key: "dueDate",
+    description: "Task completion deadline",
+    required: true,
+    editable: true
+  }
+})
+```
+
+## Advanced Updates
+
+### Batch Update Pattern
+
+Update multiple fields efficiently:
+
+```javascript
+// 1. Get schema to identify fields
+const schema = get_workflow_schema({
+  workflowId: "workflow-id"
+})
+
+// 2. Define updates
+const fieldUpdates = [
+  {
+    fieldId: "field-id-1",
+    data: { label: "Task Title", key: "taskTitle" }
+  },
+  {
+    fieldId: "field-id-2",
+    data: { label: "Due Date", key: "dueDate" }
+  },
+  {
+    fieldId: "field-id-3",
+    data: { label: "Priority", key: "priority", data: ["Low", "Medium", "High"] }
+  }
+]
+
+// 3. Apply updates
+for (const update of fieldUpdates) {
+  await update_workflow_field({
+    workflowId: "workflow-id",
+    fieldId: update.fieldId,
+    fieldData: update.data
+  })
+}
+```
+
+### Standardize Keys Across Workflows
+
+Ensure consistent naming across related workflows:
+
+```javascript
+// Standard keys for common fields
+
+// Update "Name" field in multiple workflows
+const workflows = [
+  { id: "projects-workflow-id", fieldId: "name-field-id" },
+  { id: "tasks-workflow-id", fieldId: "name-field-id" },
+  { id: "topics-workflow-id", fieldId: "name-field-id" }
+]
+
+for (const wf of workflows) {
+  await update_workflow_field({
+    workflowId: wf.id,
+    fieldId: wf.fieldId,
+    fieldData: {
+      label: "Name",
+      key: "name"  // Consistent key across workflows
+    }
+  })
+}
+```
+
+### Multi-Language Updates
+
+Update field labels for different languages:
+
+```javascript
+// English (default)
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Customer Name",
+    description: "Full name of the customer"
+  },
+  language: "en"
+})
+
+// Finnish
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Asiakkaan nimi",
+    description: "Asiakkaan koko nimi"
+  },
+  language: "fi"
+})
+
+// Swedish
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Kundnamn",
+    description: "Kundens fullständiga namn"
+  },
+  language: "sv"
+})
+```
+
+### Migrate ActivityLink Targets
+
+Update ActivityLinks when restructuring workflows:
+
+```javascript
+// Scenario: Replaced "Old Projects" workflow with "New Projects"
+
+// 1. Find all fields linking to old workflow
+const workflows = list_workflows()
+
+for (const workflow of workflows) {
+  const schema = get_workflow_schema({ workflowId: workflow._id })
+
+  for (const field of schema.fields) {
+    if (field.type === 'activitylink' &&
+        field.data.includes('old-projects-workflow-id')) {
+
+      // 2. Update to link to new workflow
+      const newData = field.data.map(id =>
+        id === 'old-projects-workflow-id' ? 'new-projects-workflow-id' : id
+      )
+
+      await update_workflow_field({
+        workflowId: workflow._id,
+        fieldId: field._id,
+        fieldData: { data: newData }
+      })
+    }
+  }
+}
+```
+
+## Multi-Field Updates
+
+### Scenario: Add Keys to All Fields
+
+```javascript
+// 1. Get workflow schema
+const schema = get_workflow_schema({
+  workflowId: "68446dc05b30685f67c6fcd4"
+})
+
+// 2. Filter fields without keys
+const fieldsNeedingKeys = schema.fields.filter(field =>
+  !field.key && field.type !== 'subheader'
+)
+
+// 3. Update each field (auto-generate keys from labels)
+for (const field of fieldsNeedingKeys) {
+  await update_workflow_field({
+    workflowId: "68446dc05b30685f67c6fcd4",
+    fieldId: field._id,
+    fieldData: {
+      label: field.label  // Key auto-generates from label
+    }
+  })
+
+  console.log(`Added key to field: ${field.label}`)
+}
+```
+
+### Scenario: Update All ActivityLinks
+
+```javascript
+// Update all ActivityLink fields to include new target workflow
+
+const schema = get_workflow_schema({
+  workflowId: "tasks-workflow-id"
+})
+
+const activityLinkFields = schema.fields.filter(f => f.type === 'activitylink')
+
+for (const field of activityLinkFields) {
+  await update_workflow_field({
+    workflowId: "tasks-workflow-id",
+    fieldId: field._id,
+    fieldData: {
+      data: [...field.data, "new-target-workflow-id"]  // Add new target
+    }
+  })
+}
+```
+
+### Scenario: Make All Date Fields Optional
+
+```javascript
+const schema = get_workflow_schema({
+  workflowId: "workflow-id"
+})
+
+const dateFields = schema.fields.filter(f =>
+  ['date', 'datetime', 'daterange', 'datetimerange'].includes(f.type)
+)
+
+for (const field of dateFields) {
+  if (field.required) {
+    await update_workflow_field({
+      workflowId: "workflow-id",
+      fieldId: field._id,
+      fieldData: {
+        required: false
+      }
+    })
+
+    console.log(`Made field optional: ${field.label}`)
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Use Keys
+
+**Bad:**
+```javascript
+// Field without key
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Customer Email"
+    // No key - API responses use field ID
+  }
+})
+```
+
+**Good:**
+```javascript
+// Field with key
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Customer Email",
+    key: "customerEmail"  // Or let it auto-generate
+  }
+})
+```
+
+### 2. Use Descriptive Labels
+
+**Bad:**
+```javascript
+{ label: "Date" }  // Which date?
+```
+
+**Good:**
+```javascript
+{ label: "Due Date", key: "dueDate" }
+{ label: "Start Date", key: "startDate" }
+{ label: "Created Date", key: "createdDate" }
+```
+
+### 3. Provide Helpful Descriptions
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Budget",
+    key: "budget",
+    description: "Total project budget in USD, including all costs and contingency"
+  }
+})
+```
+
+### 4. Use Clear Placeholders
+
+```javascript
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Phone Number",
+    key: "phoneNumber",
+    placeholder: "+1 (555) 123-4567"
+  }
+})
+```
+
+### 5. Verify Updates with get_workflow_schema
+
+```javascript
+// 1. Update field
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: { key: "newKey" }
+})
+
+// 2. Verify change
+const schema = get_workflow_schema({
+  workflowId: "workflow-id"
+})
+
+const field = schema.fields.find(f => f._id === "field-id")
+console.log("Updated field key:", field.key)
+```
+
+### 6. Update Related Documentation
+
+After field updates:
+- Update team documentation
+- Update API integration code
+- Update training materials
+- Notify users of changes
+
+### 7. Consider Backward Compatibility
+
+When updating keys used in existing code:
+
+```javascript
+// Option 1: Keep old key, add new property
+// Don't change existing key if code depends on it
+
+// Option 2: Update key and update all code
+// Search codebase for old key usage
+// Update create_activity and update_activity calls
+```
+
+### 8. Test with returnFlat
+
+After adding keys, test with returnFlat:
+
+```javascript
+// 1. Add keys
+update_workflow_field({...})
+
+// 2. Test with returnFlat
+const activities = list_activities({
+  workflowId: "workflow-id",
+  limit: 1,
+  returnFlat: true
+})
+
+console.log("Fields:", Object.keys(activities.items[0].fields))
+// Should show keys instead of field IDs
+```
+
+## Troubleshooting
+
+### Error: "Permission Denied"
+
+**Cause:** User is not workspace administrator.
+
+**Solution:**
+- Contact workspace admin
+- Request admin permissions
+- Only admins can modify workflow schemas
+
+### Error: "Workflow Not Found"
+
+**Cause:** Invalid workflow ID.
+
+**Solution:**
+```javascript
+// 1. List workflows
+list_workflows()
+
+// 2. Use correct workflow ID
+update_workflow_field({
+  workflowId: "correct-workflow-id",
+  // ...
+})
+```
+
+### Error: "Field Not Found"
+
+**Cause:** Invalid field ID.
+
+**Solution:**
+```javascript
+// 1. Get workflow schema
+const schema = get_workflow_schema({
+  workflowId: "workflow-id"
+})
+
+// 2. Find correct field ID
+const field = schema.fields.find(f => f.label === "Field Label")
+console.log("Field ID:", field._id)
+
+// 3. Use correct field ID
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: field._id,
+  // ...
+})
+```
+
+### Key Not Auto-Generating
+
+**Cause:** Auto-generation disabled or key already exists.
+
+**Solution:**
+```javascript
+// Explicitly set key
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    label: "Field Label",
+    key: "fieldKey"  // Explicit key
+  },
+  autoGenerateKey: true  // Ensure enabled (default)
+})
+```
+
+### Key Not Showing in API Responses
+
+**Cause:** Not using `returnFlat: true`.
+
+**Solution:**
+```javascript
+// Keys only appear with returnFlat
+list_activities({
+  workflowId: "workflow-id",
+  returnFlat: true  // Required for keys
+})
+```
+
+### ActivityLink Update Not Working
+
+**Cause:** Invalid target workflow IDs.
+
+**Solution:**
+```javascript
+// 1. Verify target workflows exist
+list_workflows()
+
+// 2. Use correct workflow IDs in data
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    data: ["valid-workflow-id-1", "valid-workflow-id-2"]
+  }
+})
+```
+
+### Predefined Options Not Updating
+
+**Cause:** Incorrect data format.
+
+**Solution:**
+```javascript
+// Correct: Array of strings
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: {
+    data: ["Option 1", "Option 2", "Option 3"]  // Array of strings
+  }
+})
+
+// Incorrect: Single string
+// data: "Option 1, Option 2"  // Wrong format
+```
+
+### Changes Not Visible
+
+**Cause:** Cache not refreshed.
+
+**Solution:**
+```javascript
+// Refresh schema
+const schema = get_workflow_schema({
+  workflowId: "workflow-id"
+})
+
+// Check field properties
+const field = schema.fields.find(f => f._id === "field-id")
+console.log(field)
+```
+
+## Integration with Other Tools
+
+### With install_workflow
+
+After installing, add keys to fields:
+
+```javascript
+// 1. Install workflow
+const result = install_workflow({...})
+// Returns: { "_1000": "field-real-id" }
+
+// 2. Add keys to fields
+update_workflow_field({
+  workflowId: result._0001,
+  fieldId: result._1000,
+  fieldData: {
+    label: "Task Title",
+    key: "taskTitle"
+  }
+})
+```
+
+### With get_workflow_schema
+
+Inspect before updating:
+
+```javascript
+// 1. Get current schema
+const schema = get_workflow_schema({
+  workflowId: "workflow-id"
+})
+
+// 2. Find field to update
+const field = schema.fields.find(f => f.label === "Priority")
+
+// 3. Update field
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: field._id,
+  fieldData: {
+    key: "priority",
+    data: ["Low", "Medium", "High", "Urgent"]
+  }
+})
+```
+
+### With list_activities (returnFlat)
+
+Test keys with returnFlat:
+
+```javascript
+// 1. Add key
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: { key: "priority" }
+})
+
+// 2. Test with returnFlat
+const activities = list_activities({
+  workflowId: "workflow-id",
+  returnFlat: true
+})
+
+// 3. Verify key appears
+console.log(activities.items[0].fields.priority)
+// Instead of: activities.items[0].fields["field-id"]
+```
+
+### With create_activity
+
+Use updated keys:
+
+```javascript
+// 1. Update field key
+update_workflow_field({
+  workflowId: "workflow-id",
+  fieldId: "field-id",
+  fieldData: { key: "dueDate" }
+})
+
+// 2. Create activity with key
+create_activity({
+  workflowId: "workflow-id",
+  name: "New Task",
+  fields: {
+    "dueDate": "2024-12-31"  // Use key
+  },
+  returnFlat: true
+})
+```
+
+## Summary
+
+**Key Takeaways:**
+1. ✏️ **Non-destructive** - Updates fields without losing data
+2. 🔑 **Auto-generates keys** - From field labels by default
+3. 🔒 **Admin only** - Requires workspace administrator rights
+4. 📝 **Any property** - Update labels, keys, data, descriptions, etc.
+5. 🔗 **ActivityLinks** - Update target workflows dynamically
+6. 📋 **Predefined options** - Add/remove dropdown choices
+7. ✅ **Verify changes** - Use get_workflow_schema to confirm
+
+**Quick Decision Tree:**
+
+```
+Need to update workflow field?
+│
+├─ Add readable keys? → Update with label (auto-generates key)
+├─ Change dropdown options? → Update data array
+├─ Update ActivityLink targets? → Update data with workflow IDs
+├─ Change label/description? → Update label/description properties
+├─ Change requirements? → Update required/editable properties
+└─ Multiple updates needed? → Loop through fields with updates
+```
+
+## Additional Resources
+
+- See `install-workflow-skill` for creating workflows with fields
+- See `remove-workflow-skill` for deleting workflows
+- Use `get_workflow_schema` to inspect current field properties
+- Use `list_activities` with `returnFlat: true` to test keys
+- See `hailer-api` skill for comprehensive API documentation
+- See `mcp-tools` skill for implementation patterns