@hailer/mcp 0.0.6 → 0.1.0

package/.claude/skills/SDK-workspace-setup-skill/SKILL.md

@@ -1,605 +0,0 @@
----
-name: Workspace Setup with SDK
-description: Complete guide for one-shot workspace setup - create workflows, fields, and phases using hailer-sdk ws-config commands
----
-
-# Workspace Setup with SDK - Complete Guide
-
-One-shot guide for creating complete workflow systems using `hailer-sdk ws-config` commands. Use this when users ask to create workflows, fields, and phases in their Hailer workspace.
-
-## Table of Contents
-1. [Quick Reference - One-Shot Process](#quick-reference---one-shot-process)
-2. [Critical Errors to Avoid](#critical-errors-to-avoid)
-3. [Valid Field Types](#valid-field-types)
-4. [Step-by-Step Process](#step-by-step-process)
-5. [Code Templates](#code-templates)
-6. [Complete Example](#complete-example)
-7. [Troubleshooting](#troubleshooting)
-
----
-
-## Quick Reference - One-Shot Process
-
-### Command Sequence (MUST follow this order)
-
-```bash
-# 1. Pull current state
-npm run pull
-
-# 2. Edit workflows.ts with ONLY names (no _id, no folder, no enabledUnlinkedMode)
-# 3. Create workflow will happen automatically in step 4
-
-# 4. Create workflows in Hailer
-npm run workflows-sync
-
-# 5. Pull to get real IDs (CRITICAL - directories will be renamed)
-npm run pull
-
-# 6. Now edit fields.ts and phases.ts in the NEW directories
-
-# 7. Push fields and phases
-npm run push
-
-# 8. Final pull to sync
-npm run pull
-```
-
-### Key Rules
-
-| Rule | Correct | Wrong |
-|------|---------|-------|
-| New workflow entry | `{ name: "My Workflow" }` | `{ name: "X", _id: "_001", folder: "X_001" }` |
-| Field type for dropdowns | `textpredefinedoptions` | `select`, `dropdown`, `options` |
-| Field type for links | `activitylink` | `link`, `reference`, `relation` |
-| Field type for files | NOT SUPPORTED | `files`, `file`, `attachment` |
-| Dropdown options property | `data: ["A", "B"]` | `options: ["A", "B"]` |
-
----
-
-## Critical Errors to Avoid
-
-### Error 1: Setting properties on new workflows
-
-**Error Message:**
-```
-msg: '"[0].folder" is not allowed'
-msg: '"[0]._id" is not allowed'
-```
-
-**Cause:** Trying to set `_id`, `folder`, or `enabledUnlinkedMode` when creating new workflows.
-
-**Fix:** For NEW workflows, only set `name`:
-```typescript
-// workflows.ts - CORRECT for new workflows
-export const workflows: WorkflowEntry[] = [
-  { name: "Suppliers" ,enabledUnlinkedMode:true}, // creates a dataset
-  { name: "Purchase Orders" , enabledUnlinkedMode:false}, // creates a workflow
-  { name: "Order Lines" }
-];
-```
-
-### Error 2: Invalid field type
-
-**Error Message:**
-```
-msg: '"ProcessFieldType" must be one of [activitylink, country, date, ...]'
-```
-
-**Cause:** Using invalid field type like `files`, `file`, `select`, etc.
-
-**Fix:** Only use valid field types (see [Valid Field Types](#valid-field-types) section).
-
-### Error 3: Pushing before workflows exist
-
-**Error Message:**
-```
-Workflow with ID X not found in Hailer workspace
-```
-
-**Cause:** Trying to push fields/phases before creating the workflow.
-
-**Fix:**
-1. First run `npm run workflows-sync` to create workflows
-2. Then run `npm run pull` to get real IDs
-3. Then edit fields/phases and run `npm run push`
-
-### Error 4: Using wrong activitylink IDs
-
-**Cause:** Using placeholder IDs like `_0001` instead of real workflow IDs.
-
-**Fix:** After `npm run pull`, use the REAL workflow IDs from `enums.ts`:
-```typescript
-// WRONG - placeholder ID
-data: ["_0001"]
-
-// CORRECT - real Hailer ID
-data: ["6928027f0619166b709d6944"]
-```
-
-### Error 5: Fields created but NOT visible in UI
-
-**Symptom:**
-- Activities created successfully via MCP tools
-- API confirms data is stored (`show_activity_by_id` returns all values)
-- UI only shows activity name - no fields visible in right panel
-
-**Root Cause:** The `fields: []` array in `phases.ts` is empty. Fields must be explicitly listed in each phase to display.
-
-```typescript
-// phases.ts - WRONG (fields invisible)
-{
-  name: "Active",
-  fields: [],  // ← EMPTY! Fields won't show
-}
-
-// phases.ts - CORRECT (fields visible)
-import { Suppliers_PhaseIds, Suppliers_FieldIds } from "../enums";
-
-{
-  _id: Suppliers_PhaseIds.active_6f4,
-  name: "Active",
-  fields: [
-    Suppliers_FieldIds.supplier_number_8bb,
-    Suppliers_FieldIds.street_address_8be,
-    Suppliers_FieldIds.city_8c4,
-    // ... ALL field IDs you want visible
-  ],
-}
-```
-
-**The Fix:**
-1. Import field IDs from `enums.ts`
-2. Add all field IDs to each phase's `fields: []` array
-3. Run `npm run phases-push`
-
-**Key Understanding:**
-
-| File | Purpose |
-|------|---------|
-| `fields.ts` | **Defines** what fields exist (schema) |
-| `phases.ts` → `fields: []` | **Controls** which fields are **visible** in UI |
-
-Creating fields does NOT automatically make them visible. You must add their IDs to each phase.
-
----
-
-## Valid Field Types
-
-```
-activitylink          - Link to activities in another workflow
-country               - Country selector
-date                  - Date picker
-daterange             - Date range (start/end)
-datetime              - Date and time picker
-datetimerange         - Date/time range
-numeric               - Number input
-numericunit           - Number with unit (e.g., 5 kg)
-teams                 - Team selector
-text                  - Single line text
-textarea              - Multi-line text
-textunit              - Text with unit
-textpredefinedoptions - Dropdown/select with predefined options
-time                  - Time picker
-timerange             - Time range
-users                 - User selector
-linkedfrom            - Reverse link (shows activities linking TO this one)
-subheader             - Visual separator (not a data field)
-```
-
-**NOT VALID:** `files`, `file`, `attachment`, `select`, `dropdown`, `options`, `email`, `phone`, `url`
-
----
-
-## Step-by-Step Process
-
-### Step 1: Pull Current State
-
-```bash
-npm run pull
-```
-
-This creates/updates the `workspace/` directory with current configuration.
-
-### Step 2: Edit workflows.ts
-
-Add new workflows with ONLY the `name` property:
-
-```typescript
-// workspace/workflows.ts
-export const workflows: WorkflowEntry[] = [
-  { name: "Suppliers" },
-  { name: "Purchase Orders" },
-  { name: "Order Lines" }
-];
-```
-
-### Step 3: Create Workflows
-
-```bash
-npm run workflows-sync
-```
-
-This creates the workflows in Hailer.
-
-### Step 4: Pull to Get Real IDs
-
-```bash
-npm run pull
-```
-
-**IMPORTANT:** This will:
-- Create new directories with real IDs (e.g., `suppliers_6928027f0619166b709d6944/`)
-- Generate `enums.ts` with all IDs
-- Clear field/phase files (they're empty in Hailer)
-
-### Step 5: Edit Fields and Phases
-
-Now edit the files in the NEW directories:
-
-**fields.ts:**
-```typescript
-export const fields: HailerFieldGeneric[] = [
-  {
-    label: "Company Name",
-    key: "companyName",
-    type: "text",
-    required: true
-  },
-  {
-    label: "Status",
-    key: "status",
-    type: "textpredefinedoptions",
-    data: ["Active", "Inactive", "Pending"]
-  },
-  {
-    label: "Related Order",
-    key: "relatedOrder",
-    type: "activitylink",
-    data: ["REAL_WORKFLOW_ID_HERE"]  // Use ID from enums.ts
-  }
-];
-```
-
-**phases.ts:**
-```typescript
-export const phases: HailerPhaseUpdatePayload[] = [
-  {
-    _id: ExistingPhaseId.from_enums,  // Keep existing phase ID
-    name: "Active",
-    color: "#27ae60"
-  },
-  {
-    name: "Inactive",  // New phases don't need _id
-    color: "#95a5a6"
-  }
-];
-```
-
-### Step 6: Push Changes
-
-```bash
-npm run push
-```
-
-### Step 7: Final Pull
-
-```bash
-npm run pull
-```
-
----
-
-## Code Templates
-
-### Basic Workflow Fields Template
-
-```typescript
-export const fields: HailerFieldGeneric[] = [
-  // Text fields
-  {
-    label: "Name",
-    key: "name",
-    type: "text",
-    required: true
-  },
-  {
-    label: "Description",
-    key: "description",
-    type: "textarea"
-  },
-
-  // Date fields
-  {
-    label: "Start Date",
-    key: "startDate",
-    type: "date"
-  },
-  {
-    label: "Due Date",
-    key: "dueDate",
-    type: "date"
-  },
-
-  // Numeric fields
-  {
-    label: "Amount",
-    key: "amount",
-    type: "numeric"
-  },
-
-  // Dropdown/Select
-  {
-    label: "Priority",
-    key: "priority",
-    type: "textpredefinedoptions",
-    data: ["Low", "Medium", "High", "Critical"]
-  },
-  {
-    label: "Status",
-    key: "status",
-    type: "textpredefinedoptions",
-    data: ["Draft", "Active", "Completed", "Cancelled"]
-  },
-
-  // User assignment
-  {
-    label: "Assigned To",
-    key: "assignedTo",
-    type: "users"
-  },
-
-  // Team assignment
-  {
-    label: "Team",
-    key: "team",
-    type: "teams"
-  },
-
-  // Country
-  {
-    label: "Country",
-    key: "country",
-    type: "country"
-  },
-
-  // Link to another workflow
-  {
-    label: "Related Item",
-    key: "relatedItem",
-    type: "activitylink",
-    data: ["WORKFLOW_ID_HERE"]
-  }
-];
-```
-
-### Basic Phases Template
-
-**IMPORTANT:** You must add field IDs to the `fields` array for them to be visible in the UI!
-
-```typescript
-import { MyWorkflow_PhaseIds, MyWorkflow_FieldIds } from "../enums";
-
-export const phases: HailerPhaseUpdatePayload[] = [
-  {
-    _id: MyWorkflow_PhaseIds.new_abc,  // Use existing phase ID from enums
-    name: "New",
-    color: "#3498db",  // Blue
-    isInitial: true,
-    fields: [
-      MyWorkflow_FieldIds.title_123,
-      MyWorkflow_FieldIds.description_456,
-      MyWorkflow_FieldIds.priority_789,
-      // Add ALL fields you want visible in this phase
-    ],
-  },
-  {
-    name: "In Progress",  // New phases don't need _id
-    color: "#f39c12",     // Orange
-    fields: [
-      MyWorkflow_FieldIds.title_123,
-      MyWorkflow_FieldIds.description_456,
-      MyWorkflow_FieldIds.priority_789,
-      MyWorkflow_FieldIds.assignedTo_012,
-    ],
-  },
-  {
-    name: "Completed",
-    color: "#27ae60",   // Green
-    fields: [
-      MyWorkflow_FieldIds.title_123,
-      MyWorkflow_FieldIds.completedDate_345,
-    ],
-  }
-];
-```
-
-**Note:** Each phase can show different fields. Completed tasks might show fewer fields than active ones.
-
-### Common Color Palette
-
-```
-#3498db - Blue (New, Open, Active)
-#f39c12 - Orange (In Progress, Pending, Warning)
-#9b59b6 - Purple (Review, Special)
-#27ae60 - Green (Completed, Success, Active)
-#e74c3c - Red (Cancelled, Error, Urgent)
-#95a5a6 - Gray (Inactive, Closed, Draft)
-#16a085 - Teal (Invoiced, Processed)
-#2c3e50 - Dark Blue (Archived, Completed)
-```
-
----
-
-## Complete Example
-
-### Scenario: Create a CRM System
-
-**Workflows to create:**
-1. Companies - Customer/partner companies
-2. Contacts - People at companies
-3. Deals - Sales opportunities
-
-### Step 1: Edit workflows.ts
-
-```typescript
-export const workflows: WorkflowEntry[] = [
-  { name: "Companies" },
-  { name: "Contacts" },
-  { name: "Deals" }
-];
-```
-
-### Step 2: Run workflows-sync and pull
-
-```bash
-npm run workflows-sync
-npm run pull
-```
-
-### Step 3: Edit fields.ts for each workflow
-
-**workspace/companies_[id]/fields.ts:**
-```typescript
-export const fields: HailerFieldGeneric[] = [
-  { label: "Company Name", key: "companyName", type: "text", required: true },
-  { label: "Industry", key: "industry", type: "textpredefinedoptions",
-    data: ["Technology", "Finance", "Healthcare", "Retail", "Other"] },
-  { label: "Website", key: "website", type: "text" },
-  { label: "Country", key: "country", type: "country" },
-  { label: "Annual Revenue", key: "annualRevenue", type: "numeric" },
-  { label: "Notes", key: "notes", type: "textarea" }
-];
-```
-
-**workspace/contacts_[id]/fields.ts:**
-```typescript
-export const fields: HailerFieldGeneric[] = [
-  { label: "Full Name", key: "fullName", type: "text", required: true },
-  { label: "Email", key: "email", type: "text" },
-  { label: "Phone", key: "phone", type: "text" },
-  { label: "Job Title", key: "jobTitle", type: "text" },
-  { label: "Company", key: "company", type: "activitylink",
-    data: ["COMPANIES_WORKFLOW_ID"], required: true },
-  { label: "Notes", key: "notes", type: "textarea" }
-];
-```
-
-**workspace/deals_[id]/fields.ts:**
-```typescript
-export const fields: HailerFieldGeneric[] = [
-  { label: "Deal Name", key: "dealName", type: "text", required: true },
-  { label: "Company", key: "company", type: "activitylink",
-    data: ["COMPANIES_WORKFLOW_ID"], required: true },
-  { label: "Contact", key: "contact", type: "activitylink",
-    data: ["CONTACTS_WORKFLOW_ID"] },
-  { label: "Value", key: "value", type: "numeric", required: true },
-  { label: "Currency", key: "currency", type: "textpredefinedoptions",
-    data: ["EUR", "USD", "GBP"] },
-  { label: "Close Date", key: "closeDate", type: "date" },
-  { label: "Owner", key: "owner", type: "users" },
-  { label: "Notes", key: "notes", type: "textarea" }
-];
-```
-
-### Step 4: Edit phases.ts for Deals
-
-**workspace/deals_[id]/phases.ts:**
-```typescript
-export const phases: HailerPhaseUpdatePayload[] = [
-  { _id: Deals_PhaseIds.existing_phase, name: "Lead", color: "#3498db" },
-  { name: "Qualified", color: "#9b59b6" },
-  { name: "Proposal", color: "#f39c12" },
-  { name: "Negotiation", color: "#e67e22" },
-  { name: "Won", color: "#27ae60" },
-  { name: "Lost", color: "#e74c3c" }
-];
-```
-
-### Step 5: Push and final pull
-
-```bash
-npm run push
-npm run pull
-```
-
----
-
-## Troubleshooting
-
-### "Workflow with ID X not found"
-
-**Cause:** Workflow doesn't exist in Hailer yet.
-
-**Solution:**
-```bash
-npm run workflows-sync  # Create workflows first
-npm run pull            # Get real IDs
-```
-
-### "enabledUnlinkedMode is not allowed"
-
-**Cause:** Setting properties that aren't allowed during workflow creation.
-
-**Solution:** Only use `{ name: "Workflow Name" }` for new workflows.
-
-### "ProcessFieldType must be one of..."
-
-**Cause:** Invalid field type.
-
-**Solution:** Use only valid types from the list above. Common mistakes:
-- `files` → NOT SUPPORTED (use Hailer's file attachment feature separately)
-- `select` → use `textpredefinedoptions`
-- `email` → use `text`
-
-### Fields disappear after pull
-
-**Expected behavior:** After `workflows-sync`, the pull creates NEW directories with real IDs. Your old directories (with placeholder IDs) are removed.
-
-**Solution:** Always edit fields AFTER the pull that follows `workflows-sync`.
-
-### Activitylink not working
-
-**Cause:** Using placeholder ID instead of real workflow ID.
-
-**Solution:** After pull, check `enums.ts` for real workflow IDs:
-```typescript
-// Use this ID in your activitylink data array
-data: [WorkflowIds.companies_abc123]
-// Or the raw ID
-data: ["6928027f0619166b709d6944"]
-```
-
-### Fields not visible in UI (data exists but doesn't show)
-
-**Cause:** The `fields: []` array in phases.ts is empty.
-
-**Solution:**
-1. Import field IDs: `import { MyWorkflow_FieldIds } from "../enums";`
-2. Add field IDs to each phase's `fields` array
-3. Run `npm run phases-push`
-
-See [Error 5](#error-5-fields-created-but-not-visible-in-ui) for full details.
-
----
-
-## Summary Checklist
-
-Before creating workflows:
-- [ ] Run `npm run pull` to get current state
-- [ ] Edit `workflows.ts` with ONLY `{ name: "..." }` entries
-- [ ] Run `npm run workflows-sync`
-- [ ] Run `npm run pull` to get real IDs
-- [ ] Edit fields.ts in NEW directories (with real IDs in folder names)
-- [ ] Edit phases.ts in NEW directories
-- [ ] **Add field IDs to each phase's `fields: []` array** (or fields won't be visible!)
-- [ ] Update activitylink `data` arrays with REAL workflow IDs
-- [ ] Only use valid field types (no `files`, `select`, `email`, etc.)
-- [ ] Use `data` not `options` for dropdown values
-- [ ] Run `npm run push`
-- [ ] Run `npm run pull` for final sync
-
----
-
-## Next Steps
-
-After setting up your workflow structure, use the **populate-workflow-data-skill** to learn how to add activities (data) to your workflows.