@hailer/mcp 0.0.1

package/.claude/skills/scaffold-hailer-app-skill/SKILL.md

@@ -0,0 +1,1034 @@
+---
+name: scaffold-hailer-app-skill
+description: Complete guide to ONE-SHOT Hailer app creation - scaffolds project, creates dev app, shares with workspace, and starts dev server all in one command
+---
+
+# Scaffold Hailer App Skill (ONE-SHOT SETUP)
+
+Complete guide to using the `scaffold_hailer_app` tool - a ONE-SHOT solution that scaffolds your project, creates the dev app entry in Hailer, shares it with your workspace, updates manifest.json, and starts the dev server automatically.
+
+## Table of Contents
+- [Quick Reference](#quick-reference)
+- [Overview](#overview)
+- [What's Different: One-Shot Setup](#whats-different-one-shot-setup)
+- [Core Concepts](#core-concepts)
+- [Available Templates](#available-templates)
+- [Basic Usage](#basic-usage)
+- [Common Scenarios](#common-scenarios)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Advanced Options](#advanced-options)
+- [Additional Resources](#additional-resources)
+
+## Quick Reference
+
+### Create app with one command (recommended)
+```javascript
+scaffold_hailer_app({
+  projectName: "task-manager",
+  template: "react-ts",
+  description: "Task management application"
+})
+// ✅ Project scaffolded
+// ✅ Dependencies installed
+// ✅ Dev app created in Hailer
+// ✅ App shared with workspace
+// ✅ manifest.json configured
+// ✅ Dev server started on port 3000
+// 🎉 App ready to open in Hailer!
+```
+
+### Minimal one-shot setup
+```javascript
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts"
+})
+// Everything done automatically!
+```
+
+### Fast builds with SWC
+```javascript
+scaffold_hailer_app({
+  projectName: "enterprise-app",
+  template: "react-swc-ts",
+  description: "Enterprise dashboard with fast builds"
+})
+```
+
+### Simple vanilla app
+```javascript
+scaffold_hailer_app({
+  projectName: "quick-tool",
+  template: "vanilla",
+  description: "Lightweight utility"
+})
+```
+
+### Custom options
+```javascript
+scaffold_hailer_app({
+  projectName: "analytics-dashboard",
+  template: "react-ts",
+  description: "Analytics and reporting dashboard",
+  targetDirectory: "/path/to/projects",
+  autoCreateDevApp: true,          // Create dev app (default)
+  autoShareWithWorkspace: true,    // Share with workspace (default)
+  autoStartDevServer: true,        // Start dev server (default)
+  installDependencies: true        // Install npm packages (default)
+})
+```
+
+## Overview
+
+The `scaffold_hailer_app` tool is a **ONE-SHOT SOLUTION** that handles the entire app setup process automatically:
+
+**What happens in ONE command:**
+1. ✅ Scaffolds project from official template
+2. ✅ Installs all npm dependencies
+3. ✅ Configures CORS in vite.config.ts for Hailer access
+4. ✅ Creates dev app entry in Hailer (pointing to localhost:3000)
+5. ✅ Shares app with entire workspace
+6. ✅ Updates manifest.json with app ID
+7. ✅ Starts dev server in background on port 3000
+8. ✅ **App immediately ready to open in Hailer!**
+
+**Requirements:**
+- Node.js 18+ installed
+- npm available in PATH
+- Write permissions in target directory
+- Internet connection
+- Active Hailer workspace
+
+**Time savings:**
+- **Before:** 7 manual steps (~5-10 minutes)
+- **After:** 1 command (~1-2 minutes)
+
+## What's Different: One-Shot Setup
+
+### Old Way (Manual - 7 Steps)
+```javascript
+// Step 1: Scaffold
+scaffold_hailer_app({ projectName: "my-app", template: "react-ts" })
+
+// Step 2: Navigate
+// cd my-app
+
+// Step 3: Install dependencies
+// npm install
+
+// Step 4: Start dev server
+// npm run dev
+
+// Step 5: Create dev app in Hailer
+create_app({ name: "My App (Dev)", url: "http://localhost:3000" })
+
+// Step 6: Update manifest.json with app ID
+// (manually edit file)
+
+// Step 7: Share with workspace
+add_app_member({ appId: "xxx", member: "network_xxx" })
+```
+
+### New Way (ONE-SHOT - 1 Step)
+```javascript
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  description: "My awesome app"
+})
+// Done! App ready to open in Hailer immediately! 🎉
+```
+
+### What Gets Automated
+
+| Step | Manual Approach | One-Shot Approach |
+|------|-----------------|-------------------|
+| **Scaffold project** | ✅ Manual command | ✅ Automatic |
+| **Install dependencies** | ⏱️ Run `npm install` | ✅ Automatic |
+| **Configure CORS** | ⏱️ Edit vite.config.ts | ✅ Automatic |
+| **Create dev app** | ⏱️ Call `create_app` tool | ✅ Automatic |
+| **Share with workspace** | ⏱️ Call `add_app_member` | ✅ Automatic |
+| **Update manifest** | ⏱️ Edit file manually | ✅ Automatic |
+| **Start dev server** | ⏱️ Run `npm run dev` | ✅ Automatic |
+| **Total time** | ~5-10 minutes | ~1-2 minutes |
+| **Commands needed** | 6+ commands | **1 command** |
+
+## Core Concepts
+
+### Templates
+
+Three official templates are available:
+
+| Template | Technology | Use Case | Build Speed |
+|----------|-----------|----------|-------------|
+| **react-ts** | React + TypeScript | Production apps, recommended | Standard |
+| **react-swc-ts** | React + SWC + TypeScript | Large apps needing fast builds | Fast |
+| **vanilla** | Vanilla JS/TS | Simple apps, learning | Fast |
+
+### One-Shot Parameters
+
+**Required:**
+- `projectName` - Project folder name
+- `template` - "react-ts", "react-swc-ts", or "vanilla"
+
+**Optional:**
+- `description` - App description shown in Hailer
+- `targetDirectory` - Custom location (defaults to current directory)
+- `autoCreateDevApp` - Create dev app entry (default: true)
+- `autoShareWithWorkspace` - Share with workspace (default: true)
+- `autoStartDevServer` - Start dev server (default: true)
+- `installDependencies` - Install npm packages (default: true)
+
+### What Gets Created
+
+```
+project-name/
+├── src/               # Source code
+├── public/            # Static assets
+│   └── manifest.json  # ✅ Auto-configured with app ID
+├── vite.config.ts     # Vite configuration
+├── tsconfig.json      # TypeScript configuration
+├── package.json       # Dependencies and scripts
+└── node_modules/      # ✅ Auto-installed dependencies
+```
+
+**Plus:**
+- ✅ Dev app entry in Hailer
+- ✅ App shared with workspace
+- ✅ Dev server running in background
+
+## Available Templates
+
+### react-ts (Recommended)
+
+**Best for:**
+- Production applications
+- Teams familiar with React
+- Most use cases
+
+**Example:**
+```javascript
+scaffold_hailer_app({
+  projectName: "customer-portal",
+  template: "react-ts",
+  description: "Customer management portal"
+})
+```
+
+### react-swc-ts (High Performance)
+
+**Best for:**
+- Large applications
+- Fast build times (2-10x faster)
+- Enterprise apps
+
+**Example:**
+```javascript
+scaffold_hailer_app({
+  projectName: "enterprise-dashboard",
+  template: "react-swc-ts",
+  description: "Enterprise analytics dashboard"
+})
+```
+
+### vanilla (Lightweight)
+
+**Best for:**
+- Simple utilities
+- Learning Hailer development
+- Minimal dependencies
+
+**Example:**
+```javascript
+scaffold_hailer_app({
+  projectName: "quick-report",
+  template: "vanilla",
+  description: "Quick reporting tool"
+})
+```
+
+## Basic Usage
+
+### Complete Setup in One Command
+
+```javascript
+scaffold_hailer_app({
+  projectName: "sales-dashboard",
+  template: "react-ts",
+  description: "Sales analytics and reporting"
+})
+```
+
+**Output:**
+```
+🚀 ONE-SHOT HAILER APP SETUP
+
+Project: sales-dashboard
+Template: react-ts
+Location: /current/directory/sales-dashboard
+
+⏳ Step 1/7: Creating project from template...
+✅ Project scaffolded
+
+⏳ Step 2/7: Installing dependencies...
+✅ Dependencies installed
+
+⏳ Step 3/7: Creating dev app entry in Hailer...
+✅ App created: 691ed3fa98ebad373bbe98de
+   URL: http://localhost:3000
+
+⏳ Step 4/7: Sharing app with workspace...
+✅ App shared with entire workspace
+
+⏳ Step 5/7: Updating manifest.json with app ID...
+✅ manifest.json updated with appId
+
+⏳ Step 6/7: Starting dev server on port 3000...
+✅ Dev server started in background
+   PID: 12345
+   URL: http://localhost:3000
+
+✅ Step 7/7: Setup Complete!
+
+## 🎉 Your Hailer App is Ready!
+
+**What was done:**
+- ✅ Project scaffolded from react-ts template
+- ✅ Dependencies installed
+- ✅ Dev app entry created in Hailer (ID: 691ed3fa98ebad373bbe98de)
+- ✅ App shared with entire workspace
+- ✅ manifest.json configured with app ID
+- ✅ Dev server started on http://localhost:3000
+
+## 🚀 Next Steps
+
+1. **Open the app in Hailer** - Look for "sales-dashboard" in your apps menu
+2. **Start coding** - Files in /path/to/sales-dashboard/src will hot-reload
+3. **View logs** - Check dev server output if needed
+
+## 🔗 App Info
+
+- **App ID:** 691ed3fa98ebad373bbe98de
+- **Dev URL:** http://localhost:3000
+- **Shared with:** Entire workspace
+```
+
+### That's It!
+
+Just open the app in Hailer and start coding. All setup is done automatically.
+
+## Common Scenarios
+
+### Scenario 1: Quick Dashboard App
+
+```javascript
+// One command, ready immediately
+scaffold_hailer_app({
+  projectName: "analytics-dashboard",
+  template: "react-ts",
+  description: "Analytics and metrics dashboard"
+})
+
+// Open app in Hailer and start coding!
+```
+
+### Scenario 2: Enterprise App with Fast Builds
+
+```javascript
+scaffold_hailer_app({
+  projectName: "enterprise-crm",
+  template: "react-swc-ts",
+  description: "Enterprise CRM system"
+})
+
+// SWC provides 2-10x faster builds automatically
+```
+
+### Scenario 3: Simple Utility
+
+```javascript
+scaffold_hailer_app({
+  projectName: "csv-exporter",
+  template: "vanilla",
+  description: "CSV export utility"
+})
+
+// Lightweight app ready immediately
+```
+
+### Scenario 4: Multiple Apps in Directory
+
+```javascript
+// All apps in dedicated directory
+scaffold_hailer_app({
+  projectName: "app-one",
+  template: "react-ts",
+  description: "First application",
+  targetDirectory: "/home/user/hailer-apps"
+})
+
+scaffold_hailer_app({
+  projectName: "app-two",
+  template: "react-swc-ts",
+  description: "Second application",
+  targetDirectory: "/home/user/hailer-apps"
+})
+
+// Result:
+// /home/user/hailer-apps/
+//   app-one/      (running on port 3000, first one)
+//   app-two/      (needs manual start on different port)
+```
+
+### Scenario 5: Custom Automation Options
+
+```javascript
+// Control what gets automated
+scaffold_hailer_app({
+  projectName: "custom-app",
+  template: "react-ts",
+  description: "Custom configuration",
+  autoCreateDevApp: true,        // Create dev app
+  autoShareWithWorkspace: false, // Don't share (dev only)
+  autoStartDevServer: false,     // Start manually later
+  installDependencies: true      // Install packages
+})
+
+// Dev app created but not shared, server not started
+// Good for testing before sharing
+```
+
+## Best Practices
+
+### 1. Use Descriptive Names and Descriptions
+
+```javascript
+// ❌ Bad: Generic, no description
+scaffold_hailer_app({
+  projectName: "app1",
+  template: "react-ts"
+})
+
+// ✅ Good: Clear name and description
+scaffold_hailer_app({
+  projectName: "customer-feedback-dashboard",
+  template: "react-ts",
+  description: "Customer feedback collection and analysis"
+})
+```
+
+### 2. Let Automation Handle Setup
+
+```javascript
+// ✅ Recommended: Use defaults (everything automatic)
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  description: "My application"
+})
+
+// Only disable automation for specific reasons:
+scaffold_hailer_app({
+  projectName: "team-only-app",
+  template: "react-ts",
+  description: "Team-specific tool",
+  autoShareWithWorkspace: false  // Don't share publicly
+})
+```
+
+### 3. Choose Appropriate Template
+
+Decision tree:
+```
+Is this a complex UI app?
+├─ Yes → Is performance critical?
+│         ├─ Yes → Use react-swc-ts (fastest)
+│         └─ No  → Use react-ts (recommended)
+└─ No  → Use vanilla (simple)
+```
+
+### 4. Organize Multiple Apps
+
+```javascript
+// Consistent directory structure
+const appsDir = "/home/user/workspace/hailer-apps";
+
+scaffold_hailer_app({
+  projectName: "customer-portal",
+  template: "react-ts",
+  description: "Customer portal",
+  targetDirectory: appsDir
+})
+
+scaffold_hailer_app({
+  projectName: "admin-dashboard",
+  template: "react-swc-ts",
+  description: "Admin dashboard",
+  targetDirectory: appsDir
+})
+```
+
+### 5. Start Coding Immediately
+
+```javascript
+// 1. Run one command
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  description: "My awesome app"
+})
+
+// 2. Open app in Hailer (find in apps menu)
+
+// 3. Edit code in my-app/src/
+// Changes appear live in Hailer!
+
+// No manual setup needed!
+```
+
+## Troubleshooting
+
+### Error: "Directory Already Exists"
+
+**Solution:**
+```javascript
+// Choose different name
+scaffold_hailer_app({
+  projectName: "my-app-v2",  // Different name
+  template: "react-ts",
+  description: "My app (version 2)"
+})
+
+// Or use different directory
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  description: "My app",
+  targetDirectory: "/different/path"
+})
+```
+
+### Error: "Workspace cache not available"
+
+**Problem:** Not connected to Hailer workspace.
+
+**Solution:**
+1. Verify Hailer connection
+2. Check .env.local credentials
+3. Restart MCP server if needed
+
+### Error: "Failed to create app in Hailer"
+
+**Problem:** Permission or API issue.
+
+**Solution:**
+```javascript
+// Disable automatic app creation
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  autoCreateDevApp: false  // Skip app creation
+})
+
+// Create app manually later:
+create_app({
+  name: "my-app",
+  url: "http://localhost:3000"
+})
+```
+
+### Port 3000 Already in Use
+
+**Problem:** Dev server can't start on port 3000.
+
+**Solution:**
+1. First app gets port 3000 automatically
+2. Additional apps: start manually on different ports
+3. Or stop existing server first
+
+```bash
+# Manual start on different port
+cd my-app
+PORT=3001 npm run dev
+
+# Then update app URL:
+update_app({
+  appId: "xxx",
+  name: "My App",
+  url: "http://localhost:3001"
+})
+```
+
+### Dependencies Fail to Install
+
+**Workaround:**
+Project still created successfully. Install manually:
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+### Dev Server Fails to Start
+
+**Problem:** Background server didn't start.
+
+**Solution:**
+Start manually:
+```bash
+cd my-app
+npm run dev
+```
+
+App is already created in Hailer, just needs server running.
+
+### CORS Error When Opening App in Hailer
+
+**Problem:** Browser console shows "Access to fetch at 'http://localhost:3000/manifest.json' from origin 'https://next.hailer.com' has been blocked by CORS policy"
+
+**Solution:**
+The `scaffold_hailer_app` tool automatically configures CORS in vite.config.ts. If you scaffolded the app manually or CORS is not working:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import dns from 'dns'
+
+dns.setDefaultResultOrder('verbatim');
+
+export default defineConfig({
+  plugins: [react()],
+  base: '',
+  server: {
+    port: 3000,
+    cors: {
+      origin: '*',           // Allow all origins
+      credentials: true      // Allow credentials
+    }
+  },
+})
+```
+
+**Why this is needed:**
+- Hailer loads your app from `https://next.hailer.com` (or your Hailer domain)
+- Your dev server runs on `http://localhost:3000`
+- Without CORS configuration, browsers block cross-origin requests
+- The CORS config allows Hailer to fetch your app's manifest.json and assets
+
+**Note:** The scaffold tool now automatically adds this configuration, so new apps should work immediately!
+
+## Advanced Options
+
+### Minimal Automation
+
+```javascript
+// Just scaffold project
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  installDependencies: false,
+  autoCreateDevApp: false,
+  autoStartDevServer: false
+})
+
+// Then do manual setup as needed
+```
+
+### Dev-Only Setup (Not Shared)
+
+```javascript
+// Create app but don't share
+scaffold_hailer_app({
+  projectName: "experimental-app",
+  template: "react-ts",
+  description: "Experimental features",
+  autoShareWithWorkspace: false  // Only visible to you
+})
+
+// Share later when ready:
+add_app_member({
+  appId: "xxx",
+  member: "network_workspace-id"
+})
+```
+
+### Custom Target Directory
+
+```javascript
+// Use environment variable or custom path
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  description: "My app",
+  targetDirectory: process.env.DEV_APPS_PATH || "/custom/path"
+})
+```
+
+## Hailer SDK API Reference
+
+### Critical: Correct API Usage
+
+When developing Hailer apps, you MUST use the correct Hailer SDK API patterns:
+
+#### ✅ CORRECT: Activity API
+
+```typescript
+// ✅ Use hailer.activity (SINGULAR)
+const activities = await hailer.activity.list(
+  processId,  // First parameter: workflow ID
+  phaseId,    // Second parameter: phase ID
+  options     // Third parameter: options object
+);
+
+// Example with real IDs
+const activities = await hailer.activity.list(
+  '69087299c0e0b9944c620172',  // Matches workflow
+  '69087299c0e0b9944c620173',  // Scheduled phase
+  {
+    sortBy: 'created',
+    sortOrder: 'asc',
+    limit: 20
+  }
+);
+```
+
+#### ❌ WRONG: Common Mistakes
+
+```typescript
+// ❌ WRONG: Using 'activities' (plural)
+const result = await hailer.activities.list({ ... })  // activities is undefined!
+
+// ❌ WRONG: Single object parameter
+const activities = await hailer.activity.list({
+  workflowId: 'xxx',
+  phaseId: 'yyy'
+})  // Wrong signature!
+
+// ❌ WRONG: Accessing fields directly
+match.opponent  // undefined!
+match.matchDate // undefined!
+```
+
+### Activity Data Structure
+
+Activities have a specific structure - custom fields are in the `fields` object:
+
+```typescript
+interface Activity {
+  _id: string;              // Activity ID
+  name: string;             // Activity name/title
+  process: string;          // Workflow ID
+  currentPhase: string;     // Phase ID
+  created: number;          // Timestamp
+  updated?: number;         // Timestamp
+  fields?: {                // ✅ Custom fields are here!
+    [fieldKey: string]: any
+  };
+}
+```
+
+#### ✅ CORRECT: Accessing Custom Fields
+
+```typescript
+// ✅ Access via fields object
+const opponent = match.fields?.opponent;
+const matchDate = match.fields?.matchDate;
+const competition = match.fields?.competition;
+
+// ✅ Display with fallbacks
+<span>{match.fields?.opponent?.name || match.name}</span>
+```
+
+#### ❌ WRONG: Direct Field Access
+
+```typescript
+// ❌ These will be undefined!
+const opponent = match.opponent;        // undefined
+const matchDate = match.matchDate;      // undefined
+const competition = match.competition;  // undefined
+```
+
+### Complete Working Example
+
+```typescript
+import { useEffect, useState } from 'react';
+import useHailer from './hailer/use-hailer';
+
+interface Match {
+  _id: string;
+  name: string;
+  fields?: {
+    opponent?: { _id: string; name: string };
+    matchDate?: number;
+    competition?: string;
+    venue?: string;
+  };
+}
+
+export default function MatchesList() {
+  const { hailer, inside } = useHailer();
+  const [matches, setMatches] = useState<Match[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (!hailer || !inside) return;
+
+    async function fetchMatches() {
+      try {
+        // ✅ CORRECT: activity.list with separate parameters
+        const activities = await hailer.activity.list(
+          '69087299c0e0b9944c620172',  // processId
+          '69087299c0e0b9944c620173',  // phaseId
+          {
+            sortBy: 'created',
+            sortOrder: 'asc',
+            limit: 20
+          }
+        );
+
+        setMatches(activities || []);
+      } catch (err) {
+        console.error('Failed to fetch:', err);
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    fetchMatches();
+  }, [hailer, inside]);
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {matches.map((match) => (
+        <div key={match._id}>
+          {/* ✅ CORRECT: Access via fields */}
+          <h3>{match.fields?.opponent?.name || match.name}</h3>
+          <p>Competition: {match.fields?.competition}</p>
+          <p>Venue: {match.fields?.venue}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Other Hailer SDK APIs
+
+#### Activity Operations
+
+```typescript
+// Get single activity
+const activity = await hailer.activity.get(activityId);
+
+// Create activities
+const created = await hailer.activity.create(
+  processId,
+  [
+    { name: 'Activity 1', fields: { status: 'Active' } },
+    { name: 'Activity 2', fields: { status: 'Pending' } }
+  ]
+);
+
+// Update activities
+await hailer.activity.update(
+  [
+    { _id: 'xxx', fields: { status: 'Completed' } },
+    { _id: 'yyy', name: 'New Name' }
+  ],
+  {}  // options
+);
+
+// Remove activities
+await hailer.activity.remove(['activity-id-1', 'activity-id-2']);
+```
+
+#### Workflow/Process Operations
+
+```typescript
+// Get workflow phases
+const phases = await hailer.process.getPhases(processId);
+
+// Get workflow fields
+const fields = await hailer.process.getFields(processId, phaseId);
+```
+
+#### User Operations
+
+```typescript
+// Get current user
+const user = await hailer.user.getCurrent();
+
+// Get workspace info
+const workspace = await hailer.workspace.get();
+```
+
+### Common Patterns
+
+#### Pattern 1: List Activities with Filtering
+
+```typescript
+const activities = await hailer.activity.list(
+  workflowId,
+  phaseId,
+  {
+    sortBy: 'created',
+    sortOrder: 'desc',
+    limit: 50,
+    filters: {
+      // Custom filters based on field IDs
+      fieldId: { operator: 'equals', value: 'someValue' }
+    }
+  }
+);
+```
+
+#### Pattern 2: Display Activity with Custom Fields
+
+```typescript
+function ActivityCard({ activity }: { activity: Activity }) {
+  return (
+    <div>
+      <h3>{activity.name}</h3>
+      {/* Access custom fields via fields object */}
+      <p>Status: {activity.fields?.status}</p>
+      <p>Priority: {activity.fields?.priority}</p>
+      <p>Due Date: {formatDate(activity.fields?.dueDate)}</p>
+    </div>
+  );
+}
+```
+
+#### Pattern 3: Handle ActivityLink Fields
+
+```typescript
+// ActivityLink fields are objects with _id and name
+const linkedActivity = activity.fields?.linkedField;
+
+if (linkedActivity) {
+  console.log(linkedActivity._id);   // Activity ID
+  console.log(linkedActivity.name);  // Activity name
+}
+```
+
+### TypeScript Types
+
+For better type safety, extend the Activity interface:
+
+```typescript
+interface CustomActivity extends Activity {
+  fields?: {
+    status?: string;
+    priority?: string;
+    dueDate?: number;
+    assignedTo?: { _id: string; name: string };
+    relatedActivity?: { _id: string; name: string };
+  };
+}
+```
+
+### Key Takeaways
+
+1. **Always use `hailer.activity` (singular), never `hailer.activities`**
+2. **Pass parameters separately**: `list(processId, phaseId, options)`
+3. **Access custom fields via `activity.fields?.fieldName`**
+4. **ActivityLink fields are objects with `_id` and `name` properties**
+5. **Use optional chaining (`?.`) to safely access nested fields**
+
+## Additional Resources
+
+### Related Skills
+- **create-app-skill** - Create Hailer app entries (now automatic!)
+- **publish-hailer-app-skill** - Deploy apps to production
+- **add-app-member-skill** - Share apps with users (now automatic!)
+- **list-apps-skill** - View and manage apps
+
+### Related Tools
+- `create_app` - Create app entry (now automatic!)
+- `publish_hailer_app` - Deploy to production
+- `add_app_member` - Share access (now automatic!)
+- `update_app` - Modify app properties
+- `list_apps` - View all workspace apps
+
+### Key Improvements
+
+**Before (Manual):**
+- 7 separate steps
+- 5-10 minutes
+- Error-prone
+- Easy to forget steps
+
+**After (One-Shot):**
+- 1 command
+- 1-2 minutes
+- Automated
+- Nothing to forget!
+
+### Template Comparison
+
+| Feature | react-ts | react-swc-ts | vanilla |
+|---------|----------|--------------|---------|
+| **Framework** | React 18 | React 18 | None |
+| **TypeScript** | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Compiler** | Babel/esbuild | SWC (Rust) | esbuild |
+| **Build Speed** | Standard | 2-10x faster | Fast |
+| **Bundle Size** | ~150KB | ~150KB | ~10KB |
+| **Best For** | Most apps | Large apps | Simple apps |
+
+### Complete Workflow
+
+**Development:**
+```javascript
+// 1. Create app (one command!)
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",
+  description: "My application"
+})
+
+// 2. Open in Hailer and start coding
+// App already running, shared, configured!
+
+// 3. Edit files in my-app/src/
+// Changes appear live
+
+// 4. When ready, publish
+publish_hailer_app({
+  email: "user@example.com",
+  password: "password",
+  projectDirectory: "./my-app"
+})
+```
+
+That's it! The one-shot approach eliminates all manual setup steps.
+
+---
+
+## Next Steps: Building Your App
+
+After scaffolding, you need to load data from Hailer workflows. **IMPORTANT:** The Hailer App SDK has specific patterns you must follow!
+
+### ⚠️ Critical: Load the Building Hailer Apps Skill
+
+```typescript
+// Load comprehensive guide for data loading
+await get_skill({ skillName: "building-hailer-apps-skill" })
+```
+
+**This skill covers:**
+- ✅ How to properly call `hailer.activity.list()` (3 positional params)
+- ✅ How field access works (fields are keyed by IDs, not readable keys)
+- ✅ How to use MCP tools to get workflow schema
+- ✅ Complete working examples with TypeScript
+- ✅ Common pitfalls and how to avoid them
+- ✅ Debugging techniques when data won't load
+
+**Why you need it:** The Hailer App SDK is different from the MCP API. Without this knowledge, you'll get errors like:
+- `Cannot read properties of undefined (reading 'activity')`
+- `"processId" must be a string`
+- Fields showing as `undefined` even though data loads
+
+**Load it before writing any data-loading code!**