@hailer/mcp 1.1.11 → 1.1.13

package/.claude/skills/SDK-ws-config-skill/SKILL.md

@@ -1,1139 +0,0 @@
----
-name: SDK-ws-config-skill
-description: Comprehensive workspace configuration - workflows, fields, phases
-version: 1.7.1
-triggers: Create workflow, add field, configure phase, field visibility, phase transitions
----
-
-# Workspace Configuration
-
-## File Structure
-
-```
-workspace/
-├── workflows.ts              ← Workflow registry
-├── enums.ts                  ← AUTO-GENERATED (never edit)
-├── teams.ts, groups.ts       ← Access control
-├── insights.ts               ← SQL-like reports
-└── [Workflow]_[id]/
-    ├── main.ts               ← Workflow metadata
-    ├── fields.ts             ← Field definitions
-    ├── phases.ts             ← Phase configuration
-    ├── templates.ts          ← Document templates registry
-    └── functions/*.ts        ← Calculated field code
-```
-
----
-
-## Workflows
-
-### workflows.ts
-
-```typescript
-export const workflows: WorkflowEntry[] = [
-  // NEW workflow - omit _id and folder
-  {
-    name: "Tasks",
-    enableUnlinkedMode: false
-  },
-  // EXISTING workflow - has _id and folder
-  {
-    _id: "682ac815fba468d857d498f7",
-    name: "Tasks",
-    enableUnlinkedMode: false,
-    folder: "tasks_682ac815fba468d857d498f7"
-  }
-];
-```
-
-| Property | Description |
-|----------|-------------|
-| `name` | Display name |
-| `enableUnlinkedMode` | `true` = standalone items, `false` = must link to other activities |
-| `_id` | Server-generated (omit for new) |
-| `folder` | Auto-generated on pull (omit for new) |
-
-<critical-rules>
-## CRITICAL: Workflows Require a Default Team
-
-**This is the #1 cause of "can't create activities" errors.**
-
-When you create a new workflow, it has NO default team. Without a default team:
-- `mcp__hailer__create_activity` fails
-- Apps using `hailer.activity.create()` fail
-- You get confusing permission/validation errors
-
-**Solution:** Always set a default team immediately after creating a workflow:
-
-1. Create the workflow
-2. In Hailer UI: Workflow Settings → Default Team → Select any team
-3. Or via SDK: Add `defaultTeam: TeamIds.your_team` to workflow config
-
-**For development/testing:** Any team works. Just pick one so activity creation functions properly.
-</critical-rules>
-
----
-
-### Workflow Creation Flow
-
-**Order matters: Workflow → Phases → Fields → Phase Links → Workflow Settings**
-
-All items get server-generated IDs. You must push each step and pull to get the IDs before referring to them.
-
-```
-1. npm run pull
-2. Edit workflows.ts (add new entry without _id/folder)
-3. Return ["npm run workflows-sync:force"]
-4. npm run pull (generates folder + enums with workflow ID)
-
-5. Edit phases.ts (add phases without _id, empty fields array)
-6. Return ["npm run phases-push:force"]
-7. npm run pull (generates phase IDs in enums)
-
-8. Edit fields.ts (add fields without _id)
-9. Return ["npm run fields-push:force"]
-10. npm run pull (generates field IDs in enums)
-
-11. Edit phases.ts:
-    - Add field IDs to phase.fields arrays
-    - Add possibleNextPhase arrays (phase transition links)
-12. Return ["npm run phases-push:force"]
-
-13. Edit main.ts: Set primaryDateField and primaryNumberField
-14. Return ["npm run push:force"]
-```
-
-### Workflow Permissions (main.ts)
-
-Control who can access the workflow and what they can do.
-
-```typescript
-// In main.ts
-export const workflowConfig = {
-  _id: WorkflowIds.tasks_abc,
-  name: "Tasks",
-
-  // WHO CAN ACCESS THIS WORKFLOW
-  members: [
-    {
-      id: HailerMembers.timo_ahonen_94d,  // User ID
-      permissions: ["admin"]               // Full control
-    },
-    {
-      id: WorkspaceTeams.sales_team_fc0,  // Team ID
-      permissions: ["any"]                 // Standard access
-    }
-  ],
-
-  // DEFAULT TEAM for new activities
-  preselectedTeam: {
-    account: "workspace_account_id",
-    team: WorkspaceTeams.default_team_abc
-  },
-  enablePreselectedTeam: true,
-
-  // GUEST ACCESS
-  allowGuests: false,          // Allow external guests
-  enableGuestEditing: false,   // Can guests edit?
-
-  // ... other config
-};
-```
-
-**Permission levels:**
-| Level | Meaning |
-|-------|---------|
-| `"admin"` | Full control - can edit workflow settings, delete activities |
-| `"any"` | Standard access - can view, create, edit based on phase settings |
-
-**Member types:**
-- Users: `HailerMembers.user_name_id`
-- Teams: `WorkspaceTeams.team_name_id`
-
-### Phase Permissions (phases.ts)
-
-Control visibility and behavior per phase.
-
-```typescript
-// In phases.ts
-export const phases = [
-  {
-    _id: PhaseIds.in_progress_def,
-    name: "In Progress",
-
-    // FIELD VISIBILITY - only these fields visible in this phase
-    fields: [
-      FieldIds.title_abc,
-      FieldIds.assignee_def,
-      FieldIds.due_date_ghi
-    ],
-
-    // AUTO-FOLLOWERS - notified when activity enters this phase
-    followers: [
-      WorkspaceTeams.managers_team_abc,  // Team
-      "user_id_123"                       // Or specific user
-    ],
-
-    // PHASE TRANSITIONS - where activities can move TO from here
-    possibleNextPhase: [
-      PhaseIds.review_ghi,
-      PhaseIds.done_jkl
-    ],
-
-    // TRANSITION SETTINGS (optional)
-    possibleNextPhaseSettings: {
-      [PhaseIds.done_jkl]: {
-        requireComment: true  // Must add comment when moving to Done
-      }
-    },
-
-    // WEBHOOKS - trigger external systems
-    webhooksEnabled: true,
-    webhookUrl: "https://hooks.example.com/phase-entered"
-  }
-];
-```
-
-**Key phase permissions:**
-| Setting | Purpose |
-|---------|---------|
-| `fields[]` | Which fields are visible/editable in this phase |
-| `followers[]` | Users/teams auto-notified for activities in this phase |
-| `possibleNextPhase[]` | Allowed phase transitions (empty = cannot move out) |
-| `isInitial` | New activities start here |
-| `isEndpoint` | Activities here are "complete" |
-
-### Teams & Groups (workspace root)
-
-Teams and groups are defined at workspace root level (not per-workflow).
-
-**Location:** `workspace/teams.ts` and `workspace/groups.ts`
-
-```typescript
-// workspace/teams.ts
-import { WorkspaceMembers, WorkspaceTeams } from "./enums";
-
-export const teams: HailerTeamUpdatePayload[] = [
-  {
-    _id: WorkspaceTeams.sales_team_abc,
-    name: "Sales Team",
-    description: "Sales department members",
-    members: [
-      WorkspaceMembers.john_doe_123,
-      WorkspaceMembers.jane_smith_456
-    ],
-    public: false,  // Only members can see team activities
-    defaultView: {
-      type: "app",         // "app" | "workflow" | "phase"
-      value: "app_id_here" // ID of default view
-    }
-  }
-];
-```
-
-**Team properties:**
-| Property | Purpose |
-|----------|---------|
-| `_id` | Team ID (from enums after first push) |
-| `name` | Display name |
-| `description` | Team description |
-| `members[]` | Array of user IDs (WorkspaceMembers enum) |
-| `public` | If true, visible to all workspace users |
-| `defaultView` | What opens when team is selected |
-
-**Groups** (less common) are collections of teams:
-```typescript
-// workspace/groups.ts
-export const groups: HailerGroupUpdatePayload[] = [
-  {
-    _id: GroupIds.all_managers_abc,
-    name: "All Managers",
-    teams: [TeamIds.sales_managers, TeamIds.tech_managers],
-    users: [WorkspaceMembers.ceo_123]  // Direct user members
-  }
-];
-```
-
-**Push commands:**
-```bash
-npm run teams-push:force   # Push team changes
-npm run groups-push:force  # Push group changes
-```
-
-**Where teams are used:**
-- Workflow `members[]` - who can access workflow
-- Workflow `preselectedTeam` - default team for new activities
-- Phase `followers[]` - auto-notify teams
-- App permissions - grant team access to apps
-
----
-
-<critical-rules>
-### CRITICAL: Phase Links (possibleNextPhase)
-
-**Problem:** Without phase links, users cannot move activities between phases.
-
-Every phase needs `possibleNextPhase` array defining allowed transitions:
-
-```typescript
-{
-  _id: Tasks_PhaseIds.lead_abc,
-  name: "Lead",
-  isInitial: true,
-  possibleNextPhase: [
-    Tasks_PhaseIds.qualified_def,
-    Tasks_PhaseIds.lost_ghi
-  ]
-}
-```
-
-**Without this:** Activities are stuck in their initial phase forever.
-</critical-rules>
-
-<critical-rules>
-### CRITICAL: Primary Date and Number Fields
-
-**Set in main.ts** to enable calendar view and number aggregation:
-
-```typescript
-// workspace/[Workflow]_[id]/main.ts
-export const workflowConfig = {
-  // ... other config
-  primaryDateField: Tasks_FieldIds.due_date_abc,      // For calendar view
-  primaryNumberField: Tasks_FieldIds.amount_def,      // For aggregations
-};
-```
-
-**Without primaryDateField:** Activities won't appear on the calendar.
-**Without primaryNumberField:** Number aggregations won't work in views.
-</critical-rules>
-
----
-
-## Fields
-
-### Basic Field Structure
-
-```typescript
-// In fields.ts
-import { Tasks_FieldIds, WorkflowIds } from "../enums";
-
-export const fields: HailerFieldGeneric[] = [
-  // NEW field - omit _id
-  {
-    label: "Due Date",
-    type: "date",
-    required: false
-  },
-  // EXISTING field - use enum for _id
-  {
-    _id: Tasks_FieldIds.due_date_abc,
-    label: "Due Date",
-    type: "date",
-    required: false
-  }
-];
-```
-
-### Common Field Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `_id` | string | Field ID (omit for new, use enum for existing) |
-| `label` | string | Display name shown in UI |
-| `type` | string | Field type (see below) |
-| `key` | string | URL-safe identifier (see Key Naming below) |
-| `description` | string | Help text shown below field in forms |
-| `required` | boolean | Is field required |
-| `defaultTo` | boolean | Use default value |
-| `defaultValue` | string | Default value |
-| `inviteToDiscussionOnChange` | boolean | Notify discussion on change |
-
-### Field Key Naming
-
-The `key` property is an optional URL-safe identifier for the field. If omitted, Hailer auto-generates one from the label.
-
-**Conventions:**
-- Use `snake_case` (lowercase with underscores)
-- Keep it short but descriptive
-- Use consistent prefixes for related fields
-- Avoid reserved words
-
-**Examples:**
-```typescript
-// Good keys
-{ label: "Customer Name", key: "customer_name" }
-{ label: "Invoice #", key: "invoice_number" }
-{ label: "Due Date", key: "due_date" }
-{ label: "Total (€)", key: "total_eur" }
-
-// Prefixed for grouping
-{ label: "Billing Address", key: "billing_address" }
-{ label: "Billing City", key: "billing_city" }
-{ label: "Shipping Address", key: "shipping_address" }
-{ label: "Shipping City", key: "shipping_city" }
-```
-
-**When to specify `key`:**
-- Always for fields used in integrations (APIs, Zapier, webhooks)
-- Always for fields referenced in insights or functions
-- Optional for internal-only fields (auto-generated is fine)
-
-### Field Descriptions
-
-The `description` property adds help text below the field input in Hailer forms.
-
-**When to use:**
-- Fields with non-obvious formats ("Enter date as DD.MM.YYYY")
-- Fields requiring specific values ("Must be 8-digit code")
-- Fields with business rules ("Leave empty to use default pricing")
-- Fields that differ from similar-named fields in other workflows
-
-**Examples:**
-```typescript
-{
-  label: "Project Code",
-  type: "text",
-  key: "project_code",
-  description: "8-character code from the ERP system (e.g., PRJ-12345)"
-}
-
-{
-  label: "Discount %",
-  type: "numeric",
-  key: "discount_pct",
-  description: "Enter 0-100. Applied to subtotal before VAT."
-}
-```
-
-### Field Types Reference
-
-Complete reference of all Hailer field types. Source: `hailer.d.ts` HailerFieldType.
-
-#### Quick Reference Table
-
-| Type | Use For | Value Format (CRUD) | Notes |
-|------|---------|---------------------|-------|
-| `text` | Short text (single line) | `"string"` | |
-| `textarea` | Long text (multi-line) | `"string"` | Plain text |
-| `textunit` | Text with unit suffix | `"string"` | Display unit |
-| `numeric` | Numbers | `123` or `45.67` | |
-| `numericunit` | Numbers with unit | `123` | Unit in display |
-| `date` | Single date | `1730937600000` (ms) | Unix timestamp |
-| `datetime` | Date + time | `1730937600000` (ms) | Unix timestamp |
-| `daterange` | Date span | `{start, end}` | Both timestamps |
-| `datetimerange` | Date+time span | `{start, end}` | Both timestamps |
-| `time` | Time only | `1765863000000` (ms) | Timestamp, but only time shown (e.g., "17:00") |
-| `timerange` | Time span | `{start, end}` | Timestamps, shown as "17:00 - 18:00" |
-| `textpredefinedoptions` | Dropdown select | `"Option"` | **STRING not array!** See section below. |
-| `users` | Single user | `"userId"` | STRING not array! |
-| `teams` | Team | `"teamId"` | Team selector |
-| `activitylink` | Link to activity | `"activityId"` | STRING not array! |
-| `linkedfrom` | Backlink (read-only) | N/A | Auto-populated |
-| `country` | Country picker | `"FI"` | ISO country code |
-| `subheader` | Section divider | N/A | UI only, no data |
-| `numeric` + `modifier.checkbox` | Checkbox/boolean | `1` or `0` | See Modified Fields |
-| `text` + `modifier.file` | File/picture upload | Object | See Modified Fields |
-
-**Note:** No multi-select types exist. For multiple values, use multiple fields or comma-separated text.
-
----
-
-#### Text Fields
-
-```typescript
-// Short text (single line)
-{ type: "text", label: "Title" }
-
-// Long text (multi-line, plain)
-{ type: "textarea", label: "Description" }
-
-// Text with unit suffix (e.g., "100 pcs")
-{ type: "textunit", label: "Quantity Text", unit: "pcs" }
-```
-
-**When to use:**
-- `text` - Names, titles, short answers
-- `textarea` - Descriptions, comments, notes
-- `textunit` - Text that needs a unit suffix displayed
-
----
-
-#### Number Fields
-
-```typescript
-// Plain number
-{ type: "numeric", label: "Quantity" }
-
-// Number with display unit
-{ type: "numericunit", label: "Price", unit: "€" }
-{ type: "numericunit", label: "Weight", unit: "kg" }
-```
-
-**CRITICAL:** Type is `numeric`, NOT `number`!
-
-**When to use:**
-- `numeric` - Quantities, counts, raw numbers
-- `numericunit` - Prices, measurements, amounts with units
-
----
-
-#### Date/Time Fields
-
-```typescript
-// Single date (no time)
-{ type: "date", label: "Due Date" }
-
-// Date with time
-{ type: "datetime", label: "Meeting Start" }
-
-// Date range (start + end dates)
-{ type: "daterange", label: "Project Period" }
-
-// Date+time range
-{ type: "datetimerange", label: "Event" }
-
-// Time only (no date)
-{ type: "time", label: "Start Time" }
-
-// Time range
-{ type: "timerange", label: "Working Hours" }
-```
-
-**Value format (CRUD):**
-- `date`, `datetime`: Unix timestamp in milliseconds → `1730937600000`
-- `daterange`, `datetimerange`: `{ start: 1730937600000, end: 1731024000000 }`
-- `time`: Unix timestamp (ms) → `1765863000000` (date arbitrary, only time displayed as "09:30")
-- `timerange`: `{ start: 1765863000000, end: 1765892400000 }` (shown as "09:30 - 17:30")
-
-**Time field note:** Stored as full timestamp but UI only shows time. Extract time portion when displaying:
-```javascript
-const date = new Date(timeValue);
-const hours = date.getUTCHours();
-const minutes = date.getUTCMinutes();
-```
-
-**When to use:**
-- `date` - Due dates, deadlines, birthdays
-- `datetime` - Meetings, appointments with specific time
-- `daterange` - Projects, events, bookings with duration
-- `datetimerange` - Events with specific start/end times
-- `time` - Daily schedules, opening hours
-- `timerange` - Shifts, time slots
-
----
-
-#### Selection Fields
-
-```typescript
-// Dropdown - MUST use "textpredefinedoptions"
-{
-  type: "textpredefinedoptions",
-  label: "Priority",
-  data: ["High", "Medium", "Low"]  // String array only!
-}
-```
-
-**CRITICAL FORMAT RULES:**
-- Type: `textpredefinedoptions` (NOT `dropdown`, `predefinedoptions`, `select`)
-- Property: `data` (NOT `options`)
-- Format: `["A", "B"]` (NOT `[{label: "A", value: "a"}]`)
-- **No multi-select exists** - use multiple fields if needed
-
-**Value format (CRUD):** `"High"` (STRING, not array!)
-
-```typescript
-// ✅ CORRECT
-{ type: "textpredefinedoptions", data: ["High", "Medium", "Low"] }
-
-// ❌ WRONG
-{ type: "dropdown", ... }                    // Wrong type name
-{ type: "predefinedoptions", ... }           // Missing "text" prefix
-{ options: ["A", "B"] }                      // Use data, not options
-{ data: [{label: "A", value: "a"}] }         // Use strings only
-```
-
----
-
-#### User & Team Fields
-
-```typescript
-// Single user
-{
-  type: "users",
-  label: "Assignee",
-  inviteToDiscussionOnChange: true  // Auto-invite when assigned
-}
-
-// Team
-{
-  type: "teams",
-  label: "Responsible Team"
-}
-```
-
-**Value format (CRUD):**
-- `users`: `"5f8a1b2c3d4e5f6a7b8c9d0e"` (STRING user ID)
-- `teams`: `"teamId"` (STRING team ID)
-
-**Note:** No multi-select for users/teams. Use multiple fields if needed.
-
----
-
-#### Link Fields
-
-```typescript
-// Activity link (THIS → other activity)
-{
-  type: "activitylink",
-  label: "Customer",
-  data: [WorkflowIds.customers_abc]  // Plain string array!
-}
-
-// Multiple workflow link (can link to different workflow types)
-{
-  type: "activitylink",
-  label: "Related Item",
-  data: [WorkflowIds.customers, WorkflowIds.projects]
-}
-
-// Linked from (backlink - others → THIS) - READ ONLY
-{
-  type: "linkedfrom",
-  label: "Orders",
-  data: [WorkflowIds.orders_def],
-  modifier: {
-    quickAdd: {
-      fieldIds: [],  // Fields in quick-add form
-      targetFieldId: Orders_FieldIds.customer_link
-    }
-  }
-}
-```
-
-**CRITICAL FORMAT RULES:**
-```typescript
-// ✅ CORRECT - plain string array
-data: ["697b9b54477b7e412ee08b9d"]
-data: [WorkflowIds.customers_abc]
-
-// ❌ WRONG - objects (causes API error)
-data: [{ workflowId: "697b9b54477b7e412ee08b9d" }]
-```
-
-**Value format (CRUD):**
-- `activitylink`: `"692abc123def456"` (STRING activity ID, not array!)
-
-**When to use:**
-- `activitylink` - Customer on order, project on task, parent-child relations
-- `linkedfrom` - Show related items (read-only, auto-populated from links)
-
----
-
-#### Modified Fields (Checkbox & File Upload)
-
-Fields can have a `modifier` object that changes their behavior:
-
-```typescript
-// Checkbox field = numeric + modifier.checkbox: true
-{
-  label: "Is Active",
-  type: "numeric",
-  modifier: {
-    checkbox: true,
-    file: false
-  }
-}
-
-// File/Picture upload = text + modifier.file: true
-{
-  label: "Attachments",
-  type: "text",
-  modifier: {
-    checkbox: false,
-    file: true
-  }
-}
-```
-
-**Value format (CRUD):**
-- Checkbox: `1` (true) or `0` (false) - stored as number
-- File: File reference object (handled by Hailer UI)
-
-**When to use:**
-- `modifier.checkbox: true` - Boolean yes/no, toggles
-- `modifier.file: true` - File uploads, images, attachments
-
----
-
-#### Other Fields
-
-```typescript
-// Country picker
-{ type: "country", label: "Country" }
-
-// UI organization (section divider)
-{ type: "subheader", label: "Financial Details", collapsedByDefault: true }
-```
-
-**Value format (CRUD):**
-- `country`: ISO country code → `"FI"`, `"SE"`, `"US"`
-- `subheader`: No data (UI only)
-
-**When to use:**
-- `country` - Address country, nationality
-- `subheader` - Group related fields visually
-
-**Note:** For contact info (email, phone, URL), use `text` fields.
-
----
-
-#### Calculated Function Fields
-
-```typescript
-{
-  _id: Tasks_FieldIds.total_abc,
-  label: "Total",
-  type: "numericunit",              // Output type
-  unit: "€",
-  functionEnabled: true,
-  function: "@function:total_abc",  // Function reference
-  functionVariables: {              // Input dependencies
-    quantity: {
-      type: "=",
-      data: [Tasks_FieldIds.quantity_def]
-    },
-    price: {
-      type: "=",
-      data: [Tasks_FieldIds.unit_price_ghi]
-    }
-  }
-}
-```
-
-**See `SDK-function-fields` skill for complete function field guide.**
-
----
-
-#### Field Type Limitations
-
-| Limitation | Details |
-|------------|---------|
-| **Cannot change type** | Once created, field type cannot be changed via API. Must delete and recreate (loses data) or change in Hailer UI. |
-| **linkedfrom is read-only** | Cannot set values - auto-populated from links |
-| **richtext size** | Large HTML can slow down activity loading |
-| **attachment storage** | Files stored in Hailer, count toward workspace storage |
-
-### Calculated Function Fields
-
-```typescript
-{
-  _id: Tasks_FieldIds.total_abc,
-  label: "Total",
-  type: "numericunit",
-  unit: "€",
-  functionEnabled: true,
-  function: "@function:total_abc",
-  functionVariables: {
-    quantity: {
-      type: "=",
-      data: [Tasks_FieldIds.quantity_def]
-    },
-    price: {
-      type: "=",
-      data: [Tasks_FieldIds.unit_price_ghi]
-    }
-  }
-}
-```
-
-See `SDK-function-field-variables` skill for variable types (=, >, <, ?).
-
----
-
-## Phases
-
-### Basic Phase Structure
-
-```typescript
-// In phases.ts
-import { Tasks_FieldIds, Tasks_PhaseIds } from "../enums";
-
-export const phases: HailerPhaseUpdatePayload[] = [
-  // NEW phase - omit _id
-  {
-    name: "Todo",
-    color: "#57636E",
-    fields: [],
-    possibleNextPhase: []
-  },
-  // EXISTING phase - use enum for _id
-  {
-    _id: Tasks_PhaseIds.todo_abc,
-    name: "Todo",
-    color: "#57636E",
-    fields: [
-      Tasks_FieldIds.title_def,
-      Tasks_FieldIds.assignee_ghi
-    ],
-    possibleNextPhase: [
-      Tasks_PhaseIds.in_progress_jkl,
-      Tasks_PhaseIds.done_mno
-    ]
-  }
-];
-```
-
-### Phase Properties Reference
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `_id` | string | Phase ID (omit for new) |
-| `name` | string | Display name |
-| `color` | string | Hex color (e.g., "#57636E") |
-| `description` | string | Phase description |
-
-### Phases Can Represent Different Things
-
-**Not all phases are lifecycle stages.** Check semantics before assuming flow:
-
-- **Lifecycle phases:** Draft → Review → Active → Archived
-- **Category phases:** Products workflow might use phases as categories (Doors, Windows, etc.)
-- **Status phases:** Support tickets with Open, Waiting, Resolved
-
-Always ask the user about phase semantics when creating workflows.
-
-#### Field Visibility (IMPORTANT)
-
-**Fields are NOT automatically visible in all phases.**
-
-Each phase has a `fields` array that controls which fields are visible when an activity is in that phase. A field can be:
-- Visible in ALL phases (add to every phase's `fields` array)
-- Visible in SOME phases (add only to specific phases)
-- Hidden in certain phases (omit from those phases)
-
-```typescript
-// Phase 1: Only basic fields visible
-{
-  _id: Tasks_PhaseIds.draft_abc,
-  name: "Draft",
-  fields: [
-    Tasks_FieldIds.title_def,
-    Tasks_FieldIds.description_ghi
-    // assignee and due_date NOT visible in draft
-  ]
-}
-
-// Phase 2: More fields become visible
-{
-  _id: Tasks_PhaseIds.active_jkl,
-  name: "Active",
-  fields: [
-    Tasks_FieldIds.title_def,
-    Tasks_FieldIds.description_ghi,
-    Tasks_FieldIds.assignee_mno,      // NOW visible
-    Tasks_FieldIds.due_date_pqr       // NOW visible
-  ]
-}
-```
-
-**When adding a new field:**
-1. Push the field first (`fields-push:force`)
-2. Pull to get the field ID in enums
-3. Decide which phases should show this field
-4. Add the field ID to those phases' `fields` arrays
-5. Push phases (`phases-push:force`)
-
-#### Phase Flow Control
-```typescript
-{
-  isInitial: true,           // Starting phase (activities created here)
-  isEndpoint: true,          // Final phase (workflow complete)
-  possibleNextPhase: [       // Allowed transitions
-    Tasks_PhaseIds.review_abc,
-    Tasks_PhaseIds.done_def
-  ],
-  possibleNextPhaseSettings: {
-    // Phase transition settings (optional)
-  }
-}
-```
-
-#### Calendar Integration
-```typescript
-{
-  primaryDateField: Tasks_FieldIds.due_date_abc  // Show on calendar
-  // OR
-  primaryDateField: "updated"  // Use last updated timestamp
-}
-```
-
-#### Auto-Follow
-```typescript
-{
-  followers: [
-    "user_id_abc",           // User ID
-    "team_id_def"            // Team ID
-  ]
-  // These users/teams auto-follow activities in this phase
-}
-```
-
-#### Webhooks
-```typescript
-{
-  webhooksEnabled: true,
-  webhookUrl: "https://hooks.zapier.com/..."
-  // Triggers when activity enters this phase
-}
-```
-
-#### Announcements
-```typescript
-{
-  announcementFields: [
-    Tasks_FieldIds.title_abc,
-    Tasks_FieldIds.due_date_def
-  ],
-  announcementFieldsOrder: [
-    Tasks_FieldIds.title_abc,
-    Tasks_FieldIds.due_date_def
-  ],
-  announcementRecipients: [
-    "team_id_abc"
-  ]
-  // Send notification when activity enters phase
-}
-```
-
----
-
-## Push Commands
-
-| Command | What It Does |
-|---------|--------------|
-| `npm run workflows-sync:force` | Create/update/delete workflows |
-| `npm run fields-push:force` | Create/update/delete fields |
-| `npm run phases-push:force` | Create/update/delete phases |
-| `npm run push:force` | Push all changes |
-
-**:force variants** may delete resources not in local files.
-**Non-force variants** only update, never delete.
-
-### CRITICAL: Push/Pull Order
-
-**Push FIRST, then pull.** Running pull before push overwrites local changes.
-
-```
-# CORRECT order when adding new fields locally:
-1. Edit fields.ts (add new field)
-2. npm run fields-push:force
-3. npm run pull  ← Now safe, gets generated IDs
-
-# WRONG order (loses your work):
-1. Edit fields.ts
-2. npm run pull  ← Overwrites your changes!
-```
-
-**Why?** Pull fetches server state and overwrites local files. Your unpushed edits are lost.
-
----
-
-## Common Patterns
-
-### Organizing Large Workflows with Subheaders
-
-For workflows with 15+ fields, use `subheader` fields to group related fields into collapsible sections.
-
-```typescript
-// In fields.ts - organize fields into logical groups
-export const fields: HailerFieldGeneric[] = [
-  // === BASIC INFO (always visible) ===
-  { label: "Customer Name", type: "text", required: true },
-  { label: "Contact Email", type: "text" },
-
-  // === FINANCIAL SECTION (collapsible) ===
-  {
-    type: "subheader",
-    label: "Financial Details",
-    collapsedByDefault: true  // Starts collapsed
-  },
-  { label: "Unit Price", type: "numericunit", unit: "€" },
-  { label: "Quantity", type: "numeric" },
-  { label: "Discount %", type: "numeric" },
-  { label: "Total", type: "numericunit", unit: "€", functionEnabled: true, ... },
-
-  // === DELIVERY SECTION (collapsible) ===
-  {
-    type: "subheader",
-    label: "Delivery Information",
-    collapsedByDefault: true
-  },
-  { label: "Delivery Address", type: "textarea" },
-  { label: "Delivery Date", type: "date" },
-  { label: "Delivery Notes", type: "textarea" },
-
-  // === INTERNAL/HELPER FIELDS (hidden by default) ===
-  {
-    type: "subheader",
-    label: "Internal Fields",
-    collapsedByDefault: true
-  },
-  { label: "Integration ID", type: "text" },
-  { label: "Last Sync", type: "datetime" }
-];
-```
-
-**When to use subheaders:**
-- Workflows with 15+ fields
-- Logical groupings exist (financial, delivery, contact, internal)
-- Some fields are rarely edited after initial entry
-- Helper/integration fields that clutter the UI
-
-**Subheader properties:**
-| Property | Description |
-|----------|-------------|
-| `type: "subheader"` | Required - marks as section divider |
-| `label` | Section title shown in UI |
-| `collapsedByDefault` | `true` = starts collapsed, `false` = starts expanded |
-
-**Common section patterns:**
-- "Basic Information" - core fields (often expanded)
-- "Financial Details" - prices, totals, discounts
-- "Delivery/Shipping" - addresses, dates
-- "Contact Information" - emails, phones
-- "Internal/System" - IDs, sync fields, helper fields (collapsed)
-
-**Note:** Subheaders have no data - they're UI-only for organization.
-
----
-
-### Add Field to Existing Workflow
-
-```
-1. npm run pull
-2. Edit workspace/[Workflow]_[id]/fields.ts
-   - Add new field (omit _id)
-3. Return ["npm run fields-push:force"]
-4. npm run pull (to get generated field ID in enums)
-5. Edit phases.ts - add new field ID to phase.fields arrays using enum
-6. Return ["npm run phases-push:force"]
-```
-
-### Progressive Field Visibility
-
-Common pattern: reveal more fields as activity progresses through phases.
-
-```typescript
-// Draft: minimal fields
-{ name: "Draft", fields: [title, description] }
-
-// Review: add reviewer
-{ name: "Review", fields: [title, description, reviewer] }
-
-// Active: full visibility
-{ name: "Active", fields: [title, description, reviewer, assignee, due_date, priority] }
-
-// Done: keep all visible for reference
-{ name: "Done", fields: [title, description, reviewer, assignee, due_date, priority] }
-```
-
-### Linear Phase Flow
-
-```typescript
-{
-  _id: Tasks_PhaseIds.todo_abc,
-  name: "Todo",
-  isInitial: true,
-  possibleNextPhase: [Tasks_PhaseIds.in_progress_def]
-},
-{
-  _id: Tasks_PhaseIds.in_progress_def,
-  name: "In Progress",
-  possibleNextPhase: [Tasks_PhaseIds.done_ghi]
-},
-{
-  _id: Tasks_PhaseIds.done_ghi,
-  name: "Done",
-  isEndpoint: true,
-  possibleNextPhase: []
-}
-```
-
-### Kanban-Style (Any to Any)
-
-```typescript
-const allPhases = [
-  Tasks_PhaseIds.backlog_abc,
-  Tasks_PhaseIds.todo_def,
-  Tasks_PhaseIds.doing_ghi,
-  Tasks_PhaseIds.done_jkl
-];
-
-// Each phase can move to any other
-{
-  _id: Tasks_PhaseIds.todo_def,
-  name: "Todo",
-  possibleNextPhase: allPhases.filter(p => p !== Tasks_PhaseIds.todo_def)
-}
-```
-
----
-
-## Common Mistakes
-
-| Wrong | Right |
-|-------|-------|
-| Creating fields before phases | Order: Workflow → Phases → Fields |
-| Adding `_id` to new items | Omit `_id` for new (server generates) |
-| Referencing IDs before pull | Push → Pull → Then use new IDs from enums |
-| Hardcoding IDs | Use enums from `enums.ts` |
-| Editing `enums.ts` | Never edit - auto-generated |
-| Running push commands directly | Return to orchestrator (hooks) |
-| Pulling after local edits | Push first, then pull |
-| Assuming fields auto-visible | Fields only visible if in `phase.fields` array |
-| Adding field to all phases | Ask which phases need this field visible |
-| Forgetting to add field to phases | New fields need to be in `phase.fields` |
-| Changing field type via API | Field types CANNOT be changed - see below |
-| Including `key` on existing phases | `key` only for NEW phases - push fails on existing |
-| Using `predefinedoptions` or `dropdown` | Use `textpredefinedoptions` (with "text" prefix) |
-| Using `options: [...]` for dropdowns | Use `data: [...]` (not options) |
-| `data: [{workflowId: "..."}]` for links | Use `data: ["workflowId"]` (plain string array) |
-| Forgetting `possibleNextPhase` | Activities stuck without phase transition links |
-| Missing `primaryDateField` | Activities won't show on calendar |
-
----
-
-## CRITICAL: Field Types Cannot Be Changed via API
-
-**Problem:** Once a field is created, you cannot change its `type` via the SDK push commands.
-
-**Example:** Cannot change `textarea` → `activitylink` via `npm run fields-push`
-
-**Workarounds:**
-1. Create a **new field** with the correct type (deprecate old one)
-2. Change field type manually in **Hailer UI** (Settings → Workflow → Edit field)
-3. Delete and recreate the field (loses existing data)
-
-**What CAN be changed via API:**
-- `label`, `description`, `required`
-- `data` (options for predefinedoptions, linked workflows for activitylink)
-- Field order in workflow
-
----
-
-## Checklist
-
-Before pushing workflow changes:
-
-- [ ] Used enums for all existing IDs
-- [ ] Omitted `_id` for new items
-- [ ] **Asked user which phases should show new fields**
-- [ ] New fields added ONLY to relevant `phase.fields` arrays
-- [ ] Phase transitions make sense (`possibleNextPhase`)
-- [ ] Required fields have `required: true`
-- [ ] Link fields have correct workflow IDs in `data`
-- [ ] Using `:force` variant for commands that need it
-
-When adding a new field, ALWAYS ask:
-> "Which phases should this field be visible in? All phases or specific ones?"