@hailer/mcp 1.3.14 → 1.3.23

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

@@ -1,55 +1,49 @@
 ---
 name: sdk-ws-config-skill
-description: Comprehensive workspace configuration - workflows, fields, phases
-version: 1.8.0
-triggers: Create workflow, add field, configure phase, field visibility, phase transitions, new project, init workspace, setup SDK, create workspace
+description: Workspace configuration for Hailer — workflows, fields, phases, keys, push/pull sequencing, and common creation patterns. Load this skill before creating or editing any workflow structure (workflows, fields, phases, teams, groups). Also use when you see errors like "can't create activities", phase-transition errors, field push slow acks, or questions about field types and phase visibility.
 ---
 
-# New Project Setup
+<!-- augmentation-guard: shrink-ok -->
 
-```bash
-mkdir my-hailer-project && cd my-hailer-project
-npm init -y
-npm install @hailer/sdk typescript vitest --save-dev
-```
+# Workspace Configuration
 
-Create `.env`:
-```
-HAILER_API_KEY=your_api_key
-HAILER_WORKSPACE_ID=your_workspace_id
-```
+## Push/Pull Sequencing
 
-Create `config.json`:
-```json
-{ "workspaceId": "your_workspace_id", "apiUrl": "https://api.hailer.com" }
-```
+### Decision Tree — Read First
 
-```bash
-npm run pull          # Download workspace config into workspace/
-git init
-echo ".env" >> .gitignore
-echo "node_modules" >> .gitignore
-```
+**Rule 1: Use granular per-layer commands, not `npm run push`**
 
-**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
-```
+| What you want to do | Command |
+|---------------------|---------|
+| Create a new workflow | `npm run workflows-sync:force` |
+| Update workflow properties (name, nameFunction) | `npm run workflows-push` |
+| Create or update fields | `npm run fields-push` |
+| Create or update phases | `npm run phases-push:force` |
+| Push everything at once | `npm run push:force` (only when all items already exist server-side) |
 
-**`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.
+**Rule 2: Pull only after creating new items (workflows, phases, fields) that need server-assigned IDs. Skip pull after update-only pushes — pull overwrites local changes.**
 
-**After setup:** Always set a default team on each workflow (see CRITICAL rule below).
+| Push situation | Pull after? | Why |
+|----------------|:-----------:|-----|
+| `workflows-sync:force` (new workflow) | YES | Server assigns `_id` + folder |
+| `phases-push:force` — creating new phases | YES | Server assigns phase hex IDs |
+| `fields-push` — creating new fields | YES | Server assigns field hex IDs |
+| `phases-push:force` — only updating existing phases | SKIP | No new IDs; pull overwrites local edits |
+| `fields-push` — only updating existing fields | SKIP | No new IDs |
+| `workflows-push` (nameFunction, permissions) | SKIP | Pull strips nameFunction |
 
----
+**Rule 3: Two-pass push for new entity + references to it.** Pass 1 = push the new entity only. Pull to get server-assigned ID into `enums.ts`. Pass 2 = add references using the freshly-pulled enum symbol.
 
-# Workspace Configuration
+**Rule 3b: New-workflow creation is a two-pass dance — the pull between passes is a wipe trap.**
+
+The sequence:
+1. `workflows-sync:force` creates only the workflow shell (no fields, no real phases). It reads new entries from `workflows.ts`.
+2. You MUST `npm run pull` to fetch the server-assigned workflow `_id` and rename the folder. **That pull overwrites local with server state** — it empties the renamed dir (server shell has no fields/phases yet) AND deletes any un-pushed field additions staged on other existing workflows.
+3. After pull: re-stage field/phase defs into the renamed dir → `phases-push:force` → `fields-push`.
+
+**Pull-wipe prevention guard:** before running `npm run pull` after `workflows-sync`, verify the CLI printed "✨ Created: N" (N ≥ 1). If N = 0, the create was a no-op — do NOT pull. Never stage un-pushed field-definition edits on existing workflows into the same batch as a new-workflow create-then-pull. New-workflow creation must be agent-owned end-to-end (the orchestrator cannot split edit → push → pull → re-stage across agents; the renamed dir path isn't known until after pull).
+
+---
 
 ## File Structure
 
@@ -57,7 +51,6 @@ workspace/
 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]/
@@ -76,282 +69,125 @@ workspace/
 
 ```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"
-  }
+  // NEW - omit _id and folder
+  { name: "Tasks", enableUnlinkedMode: false },
+  // EXISTING - 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
+`WorkflowEntry` schema is `{_id, name, folder, enableUnlinkedMode}` only. Do not add `key` or `description` — the server rejects them at that level. `key` is set separately via `auto_set_keys` or push path.
 
-**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>
-
----
+**CRITICAL: Workflows Require a Default Team.** Without a default team, `create_activity` fails with confusing errors. After creating a workflow: Hailer UI → Workflow Settings → Default Team.
 
 ### 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)
+2. Edit workflows.ts (add entry without _id/folder)
+3. npm run workflows-sync:force
+4. Verify "✨ Created: N" in output — if N=0, do NOT pull
+5. 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)
+6. Edit phases.ts (add phases without _id, empty fields array)
+   Use plain name strings only — enums don't exist yet for new workflows.
+7. npm run phases-push:force
+8. 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)
+9. Edit fields.ts (add fields without _id)
+10. npm run fields-push
+11. 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"]
+12. Edit phases.ts: add field IDs to phase.fields arrays + possibleNextPhase
+13. npm run phases-push:force
+    (NO pull — updates only, no new IDs)
 
-13. Edit main.ts: Set primaryDateField and primaryNumberField
-14. Return ["npm run push:force"]
+14. (If needed) Edit main.ts: add nameFunction + nameFunctionVariables
+15. npm run workflows-push
+    (NO pull — nameFunction is local, pull would overwrite it)
 ```
 
 ### 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
-    }
+    { id: HailerMembers.timo_ahonen_94d, permissions: ["admin"] },
+    { id: WorkspaceTeams.sales_team_fc0, permissions: ["any"] }
   ],
-
-  // DEFAULT TEAM for new activities
-  preselectedTeam: {
-    account: "workspace_account_id",
-    team: WorkspaceTeams.default_team_abc
-  },
+  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 |
+`members[]` (and any `HailerMemberId`-typed field) requires `HailerMembers.*` — the prefixed enum that has both Users + Teams sections. `WorkspaceTeams.*` is plain hex and fails TS2322.
 
-**Member types:**
-- Users: `HailerMembers.user_name_id`
-- Teams: `WorkspaceTeams.team_name_id`
+---
 
-### Phase Permissions (phases.ts)
+## Workflow Settings (workflowConfig toggles)
 
-Control visibility and behavior per phase.
+`primaryDateField` / `primaryNumericField` are **phase-level** — set them in `phases.ts`, not here.
 
-```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"
-  }
-];
-```
+| Toggle | Type | Notes |
+|--------|------|-------|
+| `name` | `string` | Change in `main.ts` AND `workflows.ts` before pushing. |
+| `key` | `string` | Human-readable ID (e.g. `"workOrders"`). See Keys section. |
+| `defaultView` | `"table"\|"kanban"\|"wall"\|"calendar"` | View mode on first open. |
+| `enableUnlinkedMode` | `boolean` | `true` = standalone dataset list; `false` = requires linking (kanban). Naming is inverted from intuition. |
+| `nameEditable` | `boolean` | `false` when `nameFunction` drives the title. |
+| `fieldsOrder` | `string[]` | Workflow-level field column order. |
+| `phasesOrder` | `string[]` | Phase display order. |
+| `allowGuests` | `boolean` | Grants guest/external users view access via shared link. |
+| `enableGuestEditing` | `boolean` | Lets guests edit. Requires `allowGuests: true`. |
+| `enableAttachments` | `boolean` | File attachments panel on activities. |
+| `enableMapLocation` | `boolean` | Map/location picker on activities. |
+| `enableMessenger` | `boolean` | Private messenger thread per activity. |
+| `inviteActivityCreator` | `boolean` | Automatically adds the creator as a discussion follower. Use this instead of building creator-invite logic in an app. |
+| `enableUniqueName` | `boolean` | Server rejects create/update if the activity name already exists in the workflow. |
+| `discussionPermissions` | `DiscussionPermission[]` | Controls what members can do in the discussion. |
 
-**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" |
+**Activity tagging is not configurable via `workflows-push`.** `normalizeWorkflow` strips `enableActivityTagging` from the payload. Configure activity tagging via `process.set_info` / the Hailer UI. Same class as workflow `translations`.
 
-### Teams & Groups (workspace root)
-
-Teams and groups are defined at workspace root level (not per-workflow).
-
-**Location:** `workspace/teams.ts` and `workspace/groups.ts`
+### Name Function Pattern (main.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
+nameEditable: false,
+nameFunction: "const meta = dep.activityMeta; if (!meta) return 'PREFIX-' + Date.now(); const created = Number(meta.created) || Date.now(); const year = new Date(created).getUTCFullYear(); const seq = Number(meta.sequence) || 0; let seqStr = ''; if (seq > 0) { seqStr = String(seq); while (seqStr.length < 4) seqStr = '0' + seqStr; } else { const id = meta._id || '0000'; seqStr = id.slice(-4); } return 'PREFIX-' + year + '-' + seqStr;",
+nameFunctionEnabled: true,
+nameFunctionVariables: {
+  activityMeta: { data: ["data"], type: "=" }  // magic key is "data" (NOT "meta" — "meta" silently returns null). data is plain STRINGS, not objects. type: "=" is required.
+},
 ```
 
-**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
+`nameFunction` push does NOT retroactively recompute existing activity names — existing activities keep their stored titles until next individual save.
 
 ---
 
-<critical-rules>
-### CRITICAL: Phase Links (possibleNextPhase)
-
-**Problem:** Without phase links, users cannot move activities between phases.
-
-Every phase needs `possibleNextPhase` array defining allowed transitions:
+## Teams & Groups
 
 ```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:
+// workspace/teams.ts — push: teams-push:force
+{ _id: WorkspaceTeams.sales_abc, name: "Sales", members: [WorkspaceMembers.john_123], public: false }
 
-```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
-};
+// workspace/groups.ts — push: groups-push:force
+{ _id: GroupIds.managers_abc, name: "Managers", teams: [TeamIds.sales], users: [WorkspaceMembers.ceo_123] }
 ```
 
-**Without primaryDateField:** Activities won't appear on the calendar.
-**Without primaryNumberField:** Number aggregations won't work in views.
-</critical-rules>
+**Teams — single-pass creation:**
+1. Add object **without `_id`** to `workspace/teams.ts`
+2. `npm run teams-push` — push itself creates the team
+3. `npm run pull` — writes server-assigned `_id` into `enums.ts`
+
+**Groups — two-pass creation (group `teams` can't be set in the same push that creates the group):**
+1. Add group without `_id` and with empty `teams: []` to `workspace/groups.ts`
+2. `npm run groups-push` — creates the group
+3. `npm run pull` — gets the generated `_id`
+4. Add desired `teams` array using enum symbols now in `enums.ts`
+5. `npm run groups-push` again — sets the team membership
 
 ---
 
@@ -360,153 +196,107 @@ export const workflowConfig = {
 ### 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
-  },
+  { 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
-  }
+  { _id: Tasks_FieldIds.due_date_abc, label: "Due Date", type: "date", required: false }
 ];
 ```
 
-### Common Field Properties
+**CRITICAL: Never invent an `_id` for a new item.**
 
-| 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" }
-```
+Two valid shapes for `_id`:
+1. **New item — the `_id` property is absent.** Not `null`, not `""`, not `"new"`. The key doesn't appear at all.
+2. **Existing item — `_id` references an enum symbol that already exists in `enums.ts`**.
 
-**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)
+Known failure modes:
+- `_id: "new_field_1"` — server rejects or silently miswrites
+- `_id: "000000000000000000000001"` — fake hex, same failure
+- `_id: Tasks_FieldIds.not_yet_in_enums` — TypeScript catches this only with `npx tsc --noEmit`
+- `_id: Tasks_FieldIds.some_existing_field` copied from neighbor — silently overwrites that field
 
-### Non-Obvious Field Type Notes
+### fields-push slow ack — not a hang
 
-**Checkbox** — not a distinct type. Use `numeric` + `modifier.checkbox: true` (stores `1`/`0`).
+`npm run fields-push` can appear to hang for minutes. This is **slow server-side backfill**, not a deadlock. Fields in `json_snapshot`'s dependency graph trigger synchronous snapshot recomputation across every existing activity.
 
-**File upload** — use `text` + `modifier.file: true`.
+**Fire-and-forget recipe:**
 
 ```typescript
-// Checkbox
-{ label: "Is Active", type: "numeric", modifier: { checkbox: true, file: false } }
-
-// File upload
-{ label: "Attachments", type: "text", modifier: { checkbox: false, file: true } }
-```
-
-**`linkedfrom`** (backlink) — read-only, auto-populated. Supports `modifier.quickAdd` to create related activities inline:
-
-```typescript
-{
-  type: "linkedfrom",
-  label: "Orders",
-  data: [WorkflowIds.orders_def],
-  modifier: {
-    quickAdd: {
-      fieldIds: [],  // Fields shown in quick-add form
-      targetFieldId: Orders_FieldIds.customer_link
-    }
-  }
+const TIMEOUT_MS = 30_000;
+for (const field of fieldsToPush) {
+  await Promise.race([
+    client.updateField(workflowId, field._id, field),
+    new Promise((_, rej) => setTimeout(() => rej(new Error('ack pending')), TIMEOUT_MS))
+  ]).catch(err => {
+    if (err.message === 'ack pending') {
+      console.log(`Field ${field.label}: ack pending — server is still processing`);
+    } else { throw err; }
+  });
 }
+// After all calls fired, verify: npm run pull → count fields in enums.ts
 ```
 
-**`activitylink`** — `data` must be a plain string array of workflow IDs (not objects):
-```typescript
-data: [WorkflowIds.customers_abc]             // ✅
-data: [{ workflowId: "697b9b54..." }]         // ❌ causes API error
-```
-
-**`textpredefinedoptions`** — `data` is a string array (not `options`, not objects):
-```typescript
-{ type: "textpredefinedoptions", data: ["High", "Medium", "Low"] }  // ✅
-{ type: "dropdown", options: [...] }                                  // ❌
-```
+### Common Field Properties
 
-**No multi-select types exist.** Use multiple fields if needed.
+| Property | Description |
+|----------|-------------|
+| `_id` | Omit for new, use enum for existing |
+| `label` | Display name |
+| `type` | Field type (see below) |
+| `key` | URL-safe identifier (snake_case). Specify for integration/insight fields. |
+| `description` | Help text shown below field in forms |
+| `required` | Mark essential fields required. Don't mark everything required — fields not yet known at creation time add friction. |
+| `defaultValue` | Default value |
+
+### Field Types
+
+| Type | Use For | Config Notes |
+|------|---------|-------------|
+| `text` | Short text | |
+| `textarea` | Long text | |
+| `textunit` / `numericunit` | Text/number with unit | Set `unit` property. Prefer `numericunit` over `numeric` for most numeric fields — adding a unit (€, kg, h) makes the field self-documenting. |
+| `numeric` | Numbers | NOT `number`! Unit-less values only. |
+| `date` / `datetime` | Single date/datetime | |
+| `daterange` / `datetimerange` | Date spans | |
+| `time` / `timerange` | Time only | |
+| `textpredefinedoptions` | Dropdown | `data: ["High", "Medium", "Low"]` (string array, NOT `options`, NOT `[{label,value}]`) |
+| `users` | Single-user picker | |
+| `teams` | Single-team picker | Token is `teams` (not `team`) |
+| `activitylink` | Link to activity | `data: [WorkflowIds.target]` (plain string array!) |
+| `linkedfrom` | Backlink (read-only) | Auto-populated |
+| `country` | Country picker | ISO code |
+| `subheader` | Section divider | UI only, use `collapsedByDefault: true` for grouping |
+| `numeric` + `modifier.checkbox` | Checkbox | |
+| `text` + `modifier.file` | File upload | |
+
+**No multi-select field types exist in Hailer — period.**
 
-**`time` / `timerange`** — stored as full Unix timestamp (ms) but UI shows only the time portion. Extract with `new Date(val).getUTCHours()`.
+```typescript
+// Dropdown
+{ type: "textpredefinedoptions", label: "Priority", data: ["High", "Medium", "Low"] }
 
----
+// Activity link
+{ type: "activitylink", label: "Customer", data: [WorkflowIds.customers, WorkflowIds.projects] }
+// data MUST be plain string array — data: [{workflowId: "..."}] causes API error
 
-#### Calculated Function Fields
+// Checkbox / File
+{ label: "Active", type: "numeric", modifier: { checkbox: true, file: false } }
+{ label: "Attachments", type: "text", modifier: { checkbox: false, file: true } }
 
-```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]
-    }
-  }
-}
+// numericunit — unit is a TOP-LEVEL property, NOT inside data[]
+{ label: "Amount", type: "numericunit", unit: "€", data: [] }
+// WRONG: { type: "numericunit", data: [{ unit: "€" }] } — API rejects unit inside data array
 ```
 
-**See `sdk-function-fields` skill for complete function field guide.**
+### Field Limitations
 
----
+- Cannot change field type after creation — delete and create new; new `_id` cascades into enums, phases, function field variables.
+- `linkedfrom` adding on a NEW workflow requires 2-pass push: push source workflow first → pull → push `linkedfrom` reference.
 
-#### Field Type Limitations
+### Field Visibility
 
-| 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 |
+When `fields-push` creates a new field, the server appends it to every phase's `fields[]` array automatically — field is visible everywhere immediately. Only push `phases.ts` if you want non-default placement (reordering, removing from specific phases).
 
 ---
 
@@ -515,339 +305,131 @@ data: [{ workflowId: "697b9b54..." }]         // ❌ causes API error
 ### 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
+  { name: "Todo", color: "#57636E", fields: [], possibleNextPhase: [] },
+  // EXISTING phase - use enum
   {
     _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
-    ]
+    fields: [Tasks_FieldIds.title_def, Tasks_FieldIds.assignee_ghi],
+    possibleNextPhase: [Tasks_PhaseIds.in_progress_jkl, Tasks_PhaseIds.done_mno]
   }
 ];
 ```
 
-### Phase Properties Reference
+### Phase Properties
 
 | 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
+| `key` | string | URL-safe identifier (snake_case) |
+| `color` | string | Hex color — set on every phase |
+| `fields[]` | FieldId[] | Fields visible in this phase |
+| `isInitial` | boolean | New activities start here |
+| `isEndpoint` | boolean | Activities here are "complete" |
+| `possibleNextPhase[]` | PhaseId[] | Allowed transitions — without this, activities are stuck forever |
+| `followers[]` | string[] | Users/teams auto-notified |
 
-**Not all phases are lifecycle stages.** Check semantics before assuming flow:
+**CRITICAL: Phase Links (possibleNextPhase) — without them, activities are stuck forever.**
 
-- **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
+**CRITICAL: Primary Date and Number Fields are phase properties, not workflow properties.**
 
-Always ask the user about phase semantics when creating workflows.
+| Property | Accepted values | Use a custom field ID? |
+|---|---|---|
+| `primaryDateField` | `"created"` \| `"updated"` \| `"completedOn"` \| `undefined` | No — TS rejects custom field IDs |
+| `primaryNumericField` | `string` (field ID) \| `undefined` | Yes — pass the field ID enum |
 
-#### Field Visibility (IMPORTANT)
+Setting them via `process.set_info` (workflow-level) fails with error code 191.
 
-**Fields are NOT automatically visible in all phases.**
+**Dropping a phase is destructive — all activities in that phase are cascade-deleted.** Verify count before removing (`list_activities` with `countOnly:true`). Move activities to another phase first. No undo.
 
-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)
+**`possibleNextPhase` enforces phase walks — intermediate phases cannot be skipped.** If a phase only allows certain next phases, jumping to a non-adjacent phase fails silently with `[object Object]` error. Walk the chain in hops.
 
-```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
-  ]
-}
-```
+**Disabling a phase webhook:** Set `webhooksEnabled: false` and keep `webhookUrl` as any non-empty string. Setting `webhookUrl: ""` causes error 191. `webhookAdded`/`webhookUpdated` flags are immutable from SDK side — flip the webhook toggle in Hailer UI instead.
 
-**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 Configuration Defaults
 
-#### 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
-}
-```
+1. **Set a `color` on every phase.** Uncoloured phases are indistinguishable on the board.
+2. **Set primaryDate/Numeric only when meaningful.** For reference/Register-archetype datasets, leaving both unset is correct.
 
 ---
 
-## 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.
+## Human-Readable Keys (workflow / phase / field)
 
-### Push vs Sync — What Each Command Does
+**When keys matter:**
+- Hailer apps (`@hailer/app-sdk`) — read fields by key via scaffolded `field-resolver.ts`
+- MCP tools — accept keys anywhere they accept IDs
+- Direct REST integrations — human-readable URLs/bodies
+- Marketplace-distributable apps — must use keys (installed workflow IDs differ per tenant)
 
-| 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 |
+**When keys don't matter:** Insights (use enums), Function fields (enum substitution at compile time).
 
-**Key rule:** Use `sync` to create or delete; use `push` to update existing config. For fields, `push` handles all three operations.
+### Where keys work — production-verified
 
-### CRITICAL: Push/Pull Order
+| Surface | Keys work? |
+|---|---|
+| MCP tools (`list_activities`, `create_activity`, etc.) | Yes |
+| Direct REST — `v3.activity.list/createMany/updateMany` — `phaseId` and field refs | Yes |
+| Direct REST — `processId` (workflow) | No — hex only |
+| Direct REST — `v3.activity.list` response with `returnFlat: true` | Fields keyed by key name (if field has `key` set) |
+| Insight SQL | No |
+| Activity IDs | Never — always 24-char hex |
 
-**Push FIRST, then pull.** Running pull before push overwrites local changes.
+### Easiest setup — `auto_set_keys`
 
 ```
-# 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!
+auto_set_keys({ workflowId: 'hex-id' })
 ```
 
-**Why?** Pull fetches server state and overwrites local files. Your unpushed edits are lost.
+- Derives camelCase keys from names/labels across the workflow, phases, and fields
+- Skips entities that already have a key
+- **Phase key writes fail silently in `auto_set_keys`** (known MCP bug). Set phase keys via push path instead: add `key` to each phase in `phases.ts` and run `npm run phases-push`.
+- The push path is recommended for all three key types (workflow, field, phase) — they round-trip cleanly.
 
 ---
 
-## Common Patterns
+## Push Commands Reference
 
-### Organizing Large Workflows with Subheaders
+### Deleted Workflow Cleanup
 
-For workflows with 15+ fields, use `subheader` fields to group related fields into collapsible sections.
+After deleting a workflow in Hailer and running `npm run pull`:
+- The workflow's directory is auto-removed
+- Enum references in other `workspace/*.ts` files are NOT cleaned up
 
-```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" }
-];
+After delete + pull:
+```bash
+grep -r "deleted_workflow_id" workspace/
 ```
+Fix stale references before next push.
 
-**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
+### Renaming a 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"]
+1. Change name in workflows.ts AND main.ts
+2. npm run workflows-push
+3. npm run pull
 ```
 
-### 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] }
+After rename: re-grep `enums.ts` for actual generated member names — they often shift to Finnish-label-derived stems.
 
-// 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: []
-}
-```
+## Common Patterns
 
-### Kanban-Style (Any to Any)
+### Add Field to Existing Workflow
+1. Edit `fields.ts` (omit `_id` for new) → `npm run fields-push` → `pull` (need new field IDs)
+2. Add field ID to relevant `phase.fields` arrays → `phases-push:force` (no pull needed)
 
-```typescript
-const allPhases = [
-  Tasks_PhaseIds.backlog_abc,
-  Tasks_PhaseIds.todo_def,
-  Tasks_PhaseIds.doing_ghi,
-  Tasks_PhaseIds.done_jkl
-];
+### Phase Flow Patterns
+- **Linear:** Each phase points to next only. End phase: `isEndpoint: true, possibleNextPhase: []`
+- **Kanban:** Each phase's `possibleNextPhase` includes all other phases
+- **Progressive visibility:** Early phases show fewer fields, later phases show more
 
-// Each phase can move to any other
-{
-  _id: Tasks_PhaseIds.todo_def,
-  name: "Todo",
-  possibleNextPhase: allPhases.filter(p => p !== Tasks_PhaseIds.todo_def)
-}
-```
+### Subheaders
+For 15+ fields, use `{ type: "subheader", label: "Section", collapsedByDefault: true }` to group.
 
 ---
 
@@ -856,53 +438,16 @@ const allPhases = [
 | 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 |
-| 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! |
-
----
-
-## 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?"
+| Adding `_id` to new items | Omit — server generates |
+| `npm run pull` before push | Push first, then pull only if new IDs needed |
+| Hardcoding IDs / editing `enums.ts` | Use enums, never edit |
+| Manually wiring new fields into phases | New fields auto-wire into ALL phases on creation; only push `phase.fields[]` for non-default placement |
+| `workflows-push` for new workflow | `workflows-sync:force` |
+| `type: "dropdown"`, `options: [...]` | `type: "textpredefinedoptions"`, `data: [...]` |
+| Forgetting `possibleNextPhase` | Activities stuck forever |
+| `{ type: "numericunit", data: [{ unit: "€" }] }` | `{ type: "numericunit", unit: "€", data: [] }` — unit is top-level |
+| `enableUnlinkedMode: true` = requires linking | Inverted: `true` = standalone items (dataset), `false` = requires linking |
+| `primaryDateField` in `main.ts` | Set on phases in `phases.ts` |
+| `primaryNumberField` (typo) | `primaryNumericField` |
+| Pulling without reading "✨ Created: N" first | If N=0, pull wipes local edits without creating anything |
+| Batching un-pushed field additions with a new-workflow create | Un-pushed fields get wiped by the create-pull; push existing-workflow changes first |