@hailer/mcp 1.1.16 → 1.1.17-beta.1

package/.claude/skills/{SDK-ws-config-skill → sdk-ws-config-skill}/SKILL.md

@@ -1,8 +1,52 @@
 ---
-name: SDK-ws-config-skill
+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
+version: 1.8.0
+triggers: Create workflow, add field, configure phase, field visibility, phase transitions, new project, init workspace, setup SDK, create workspace
+---
+
+# New Project Setup
+
+```bash
+mkdir my-hailer-project && cd my-hailer-project
+npm init -y
+npm install @hailer/sdk typescript vitest --save-dev
+```
+
+Create `.env`:
+```
+HAILER_API_KEY=your_api_key
+HAILER_WORKSPACE_ID=your_workspace_id
+```
+
+Create `config.json`:
+```json
+{ "workspaceId": "your_workspace_id", "apiUrl": "https://api.hailer.com" }
+```
+
+```bash
+npm run pull          # Download workspace config into workspace/
+git init
+echo ".env" >> .gitignore
+echo "node_modules" >> .gitignore
+```
+
+**Project structure after pull:**
+```
+workspace/
+├── workflows.ts, enums.ts (AUTO-GENERATED), teams.ts, groups.ts
+├── hailer.d.ts            ← AUTO-GENERATED (never edit)
+└── [Workflow]_[id]/
+    ├── main.ts, fields.ts, phases.ts
+    └── functions/*.ts
+```
+
+**`npm run pull` vs `npm run generate`:**
+- `npm run pull` — Downloads workspace config into `workspace/` (editable TypeScript files: fields, phases, workflows, enums, etc.)
+- `npm run generate` — Generates `hailer-types.ts` (a single file with workflow/phase/field enums for use in app code). These are separate commands serving different purposes.
+
+**After setup:** Always set a default team on each workflow (see CRITICAL rule below).
+
 ---
 
 # Workspace Configuration
@@ -13,6 +57,7 @@ triggers: Create workflow, add field, configure phase, field visibility, phase t
 workspace/
 ├── workflows.ts              ← Workflow registry
 ├── enums.ts                  ← AUTO-GENERATED (never edit)
+├── hailer.d.ts               ← AUTO-GENERATED (never edit)
 ├── teams.ts, groups.ts       ← Access control
 ├── insights.ts               ← SQL-like reports
 └── [Workflow]_[id]/
@@ -379,312 +424,51 @@ The `key` property is an optional URL-safe identifier for the field. If omitted,
 - 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
+### Non-Obvious Field Type Notes
 
-**Value format (CRUD):** `"High"` (STRING, not array!)
+**Checkbox** — not a distinct type. Use `numeric` + `modifier.checkbox: true` (stores `1`/`0`).
 
-```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
+**File upload** — use `text` + `modifier.file: true`.
 
 ```typescript
-// Single user
-{
-  type: "users",
-  label: "Assignee",
-  inviteToDiscussionOnChange: true  // Auto-invite when assigned
-}
+// Checkbox
+{ label: "Is Active", type: "numeric", modifier: { checkbox: true, file: false } }
 
-// Team
-{
-  type: "teams",
-  label: "Responsible Team"
-}
+// File upload
+{ label: "Attachments", type: "text", modifier: { checkbox: false, file: true } }
 ```
 
-**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
+**`linkedfrom`** (backlink) — read-only, auto-populated. Supports `modifier.quickAdd` to create related activities inline:
 
 ```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
+      fieldIds: [],  // Fields shown in quick-add form
       targetFieldId: Orders_FieldIds.customer_link
     }
   }
 }
 ```
 
-**CRITICAL FORMAT RULES:**
+**`activitylink`** — `data` must be a plain string array of workflow IDs (not objects):
 ```typescript
-// ✅ CORRECT - plain string array
-data: ["697b9b54477b7e412ee08b9d"]
-data: [WorkflowIds.customers_abc]
-
-// ❌ WRONG - objects (causes API error)
-data: [{ workflowId: "697b9b54477b7e412ee08b9d" }]
+data: [WorkflowIds.customers_abc]             // ✅
+data: [{ workflowId: "697b9b54..." }]         // ❌ causes API error
 ```
 
-**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:
-
+**`textpredefinedoptions`** — `data` is a string array (not `options`, not objects):
 ```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 }
+{ type: "textpredefinedoptions", data: ["High", "Medium", "Low"] }  // ✅
+{ type: "dropdown", options: [...] }                                  // ❌
 ```
 
-**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
+**No multi-select types exist.** Use multiple fields if needed.
 
-**Note:** For contact info (email, phone, URL), use `text` fields.
+**`time` / `timerange`** — stored as full Unix timestamp (ms) but UI shows only the time portion. Extract with `new Date(val).getUTCHours()`.
 
 ---
 
@@ -711,7 +495,7 @@ Fields can have a `modifier` object that changes their behavior:
 }
 ```
 
-**See `SDK-function-fields` skill for complete function field guide.**
+**See `sdk-function-fields` skill for complete function field guide.**
 
 ---
 
@@ -724,31 +508,6 @@ Fields can have a `modifier` object that changes their behavior:
 | **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
@@ -920,6 +679,18 @@ Each phase has a `fields` array that controls which fields are visible when an a
 **:force variants** may delete resources not in local files.
 **Non-force variants** only update, never delete.
 
+### Push vs Sync — What Each Command Does
+
+| Command | Creates | Updates | Deletes |
+|---------|---------|---------|---------|
+| `workflows push` | No | Yes | No |
+| `workflows sync` | Yes | No | Yes |
+| `fields push` | Yes | Yes | Yes (with confirmation) |
+| `templates push` | No | Yes | No |
+| `templates sync` | Yes | No | Yes |
+
+**Key rule:** Use `sync` to create or delete; use `push` to update existing config. For fields, `push` handles all three operations.
+
 ### CRITICAL: Push/Pull Order
 
 **Push FIRST, then pull.** Running pull before push overwrites local changes.
@@ -1096,11 +867,9 @@ const allPhases = [
 | 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 |
+| Two fields with same name/label | One will be removed during push — deduplicate labels! |
 
 ---