@hailer/mcp 0.0.6 → 0.1.1

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

@@ -1,1314 +0,0 @@
----
-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.
-
----
-
-## ⚠️ MANDATORY: SPAWN BUILDER AGENT AFTER SCAFFOLDING
-
-**THIS IS NOT OPTIONAL.** After `scaffold_hailer_app` completes successfully, you MUST:
-
-1. **IMMEDIATELY spawn the app builder agent** using the Task tool
-2. **DO NOT** start building components in the current session
-3. **DO NOT** skip this step
-
-### Why This Is Required
-
-- The builder agent has **isolated context** for focused work
-- It's **pre-loaded with TypeScript + SDK patterns**
-- Building in main session leads to **context overflow** and **mistakes**
-- The agent produces **higher quality code**
-
-### Exact Steps After Scaffold Succeeds
-
-```javascript
-// Step 1: Get workflow context (REQUIRED)
-list_workflows_minimal()
-
-// Step 2: Spawn the builder agent with Task tool
-Task({
-  subagent_type: "general-purpose",
-  description: "Build Hailer app components",
-  prompt: `You are building a Hailer app.
-
-PROJECT: <project-path>
-DESCRIPTION: <from scaffold description>
-WORKFLOWS: <paste list_workflows_minimal output>
-
-Load these skills FIRST:
-1. Skill("building-hailer-apps-skill")
-2. Skill("hailer-app-builder")
-
-Then build the app components following the patterns in those skills.
-
-Requirements:
-- Use Chakra UI for components
-- Follow TypeScript strict mode
-- Use hailer.activity.list(workflowId, phaseId, options) - 3 params
-- Access fields via activity.fields?.[fieldId]
-- Build full CRUD: list, create, edit, delete
-`
-})
-```
-
-### DO NOT PROCEED WITHOUT SPAWNING
-
-If you find yourself writing React components after scaffolding WITHOUT spawning an agent first, **STOP** and spawn the agent.
-
----
-
-## 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.
-
-### Infinite Loop When Loading Data
-
-**Problem:** App keeps re-fetching data infinitely, causing performance issues.
-
-**Cause:** Using `hailer` object in useEffect dependencies. The `hailer` object from `useHailer()` changes reference on every render.
-
-**Solution:**
-```typescript
-// ❌ WRONG - causes infinite loop
-useEffect(() => {
-  if (!hailer) return;
-  hailer.activity.list(...);
-}, [hailer]); // hailer changes every render!
-
-// ✅ CORRECT - use `inside` and access hailer from window
-useEffect(() => {
-  if (!inside) return;
-  const hailer = (window as any).hailerApiInstance;
-  if (!hailer) return;
-  hailer.activity.list(...);
-}, [inside]); // inside is a stable boolean
-```
-
-### Chakra UI Table Not Showing Text
-
-**Problem:** Table rows render but text is invisible/white.
-
-**Cause:** CSS inheritance issues when running inside Hailer iframe.
-
-**Solution:** Add explicit `color="black"` to Td components:
-```typescript
-<Tr key={activity._id} bg="white">
-  <Td color="black">{value}</Td>
-</Tr>
-```
-
-### 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 generic IDs (replace with actual IDs from your workspace)
-const activities = await hailer.activity.list(
-  workflowId,  // Get from list_workflows_minimal() or hailer.workflow.list()
-  phaseId,     // Get from hailer.workflow.get(workflowId).phases
-  {
-    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
-
-**⚠️ CRITICAL: Do NOT use `hailer` in useEffect dependencies - it causes infinite loops!**
-
-```typescript
-import { useEffect, useState, useRef } from 'react';
-import useHailer from './hailer/use-hailer';
-
-// Define your activity interface based on workflow fields
-interface Activity {
-  _id: string;
-  name: string;
-  fields?: {
-    [fieldId: string]: { type: string; value: unknown };  // Fields have type and value
-  };
-}
-
-interface Props {
-  workflowId: string;
-  phaseId: string;
-}
-
-export default function ActivityList({ workflowId, phaseId }: Props) {
-  const { hailer, inside } = useHailer();
-  const [activities, setActivities] = useState<Activity[]>([]);
-  const [loading, setLoading] = useState(true);
-  const loadedRef = useRef(false);
-
-  useEffect(() => {
-    // ✅ Use `inside` as trigger - it's stable
-    if (!inside) return;
-    if (loadedRef.current) return;
-
-    // ✅ Access hailer from window to avoid reference changes
-    const hailerApi = (window as any).hailerApiInstance;
-    if (!hailerApi) return;
-
-    async function fetchActivities() {
-      try {
-        // ✅ CORRECT: activity.list with separate parameters
-        const result = await hailerApi.activity.list(
-          workflowId,
-          phaseId,
-          {
-            sortBy: 'created',
-            sortOrder: 'asc',
-            limit: 50
-          }
-        );
-
-        setActivities(result || []);
-        loadedRef.current = true;
-      } catch (err) {
-        console.error('Failed to fetch:', err);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetchActivities();
-  }, [inside, workflowId, phaseId]); // ✅ NO hailer in deps!
-
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <div>
-      {activities.map((activity) => (
-        <div key={activity._id}>
-          <h3>{activity.name}</h3>
-          {/* Access fields: activity.fields?.[fieldId]?.value */}
-        </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 Operations
-
-```typescript
-// Get workflow with fields and phases
-const workflow = await hailer.workflow.get(workflowId);
-// workflow.fields = { fieldId: { label, type, key, ... } }
-// workflow.phases = { phaseId: { name, fields: [...] } }
-
-// List all workflows
-const workflows = await hailer.workflow.list();
-```
-
-#### 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: SPAWN THE BUILDER AGENT (MANDATORY)
-
-**⚠️ DO NOT BUILD IN CURRENT SESSION.** After scaffolding completes:
-
-### Step 1: Get Workflow Context
-
-```javascript
-list_workflows_minimal()
-```
-
-### Step 2: Spawn the Builder Agent
-
-```javascript
-Task({
-  subagent_type: "general-purpose",
-  description: "Build Hailer app components",
-  prompt: `You are building a Hailer app.
-
-PROJECT PATH: /path/to/project
-DESCRIPTION: <description from scaffold>
-APP TYPE: Full CRUD application
-
-WORKFLOWS IN WORKSPACE:
-<paste list_workflows_minimal output here>
-
-## MANDATORY: Load Skills First
-
-Before writing ANY code, load these skills:
-1. Skill("building-hailer-apps-skill") - SDK API patterns
-2. Skill("hailer-app-builder") - TypeScript standards
-
-## ⚠️ CRITICAL FIRST STEP: Fix main.tsx
-
-**THE TEMPLATE IS MISSING ChakraProvider!** You MUST fix this FIRST or styles won't work:
-
-\`\`\`typescript
-// src/main.tsx - REPLACE the entire file with this:
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { ChakraProvider } from '@chakra-ui/react'
-import App from './App.tsx'
-import './index.css'
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <ChakraProvider>
-      <App />
-    </ChakraProvider>
-  </React.StrictMode>,
-)
-\`\`\`
-
-**If you skip this, the app will render with NO STYLES!**
-
-## Data Loading Pattern (CRITICAL - PREVENTS INFINITE LOOPS)
-
-**⚠️ THE `hailer` OBJECT CHANGES ON EVERY RENDER!** Using `hailer` in useEffect dependencies causes infinite loops.
-
-Use `inside` boolean as the trigger and access hailer from window:
-
-\`\`\`typescript
-import { useState, useEffect, useRef } from 'react';
-
-// Hook takes `inside` boolean, NOT hailer object
-function useMyData(inside: boolean) {
-  const [data, setData] = useState([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [refreshTrigger, setRefreshTrigger] = useState(0);
-  const loadedRef = useRef(false);
-
-  useEffect(() => {
-    // Use `inside` as trigger - it's a stable boolean
-    if (!inside) return;
-    if (loadedRef.current && refreshTrigger === 0) return;
-
-    // Access hailer from window to avoid reference changes
-    const hailer = (window as any).hailerApiInstance;
-    if (!hailer) return;
-
-    async function loadData() {
-      try {
-        setLoading(true);
-        setError(null);
-
-        // 3 positional params: workflowId, phaseId, options
-        const result = await hailer.activity.list(
-          WORKFLOW_ID,
-          PHASE_ID,
-          { limit: 100 }
-        );
-
-        setData(result || []);
-        loadedRef.current = true;
-      } catch (err) {
-        setError(err instanceof Error ? err.message : 'Failed to load');
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    loadData();
-  }, [inside, refreshTrigger]); // ✅ inside is stable, hailer is NOT
-
-  const refresh = () => {
-    loadedRef.current = false;
-    setRefreshTrigger(prev => prev + 1);
-  };
-
-  return { data, loading, error, refresh };
-}
-\`\`\`
-
-**In App.tsx, pass `inside` not `hailer`:**
-\`\`\`typescript
-export default function App() {
-  const { hailer, inside } = useHailer();
-  const { data, loading, error } = useMyData(inside); // ✅ Pass inside, not hailer
-
-  if (!hailer || !inside) {
-    return <Spinner />;
-  }
-  // ...
-}
-\`\`\`
-
-**KEY RULES:**
-1. ❌ NEVER use `hailer` in useEffect dependencies - causes infinite loops
-2. ✅ Use `inside` boolean as the stable trigger
-3. ✅ Access hailer via `(window as any).hailerApiInstance` inside useEffect
-4. ✅ Use `loadedRef` to prevent duplicate loads
-
-## Field Access Pattern
-
-Fields are keyed by FIELD IDs, not readable names:
-
-\`\`\`typescript
-// Get field IDs from get_workflow_schema() first!
-const FIELDS = {
-  PLAYER_NAME: '691ffdf84217e9e8434e5694',  // From schema
-  JERSEY_NUMBER: '691ffdf84217e9e8434e5695',
-};
-
-// Helper function
-function getFieldValue<T>(fields: Record<string, {value: unknown}> | undefined, fieldId: string): T | null {
-  return (fields?.[fieldId]?.value as T) ?? null;
-}
-
-// Usage
-const name = getFieldValue<string>(activity.fields, FIELDS.PLAYER_NAME);
-\`\`\`
-
-## Requirements
-
-Build a functional app with:
-- Dashboard showing overview stats
-- List view with data from workflows
-- Proper error handling and loading states
-- Styled with Chakra UI (AFTER fixing main.tsx!)
-
-## Technical Requirements
-
-- Fix main.tsx with ChakraProvider FIRST
-- Chakra UI components for all UI
-- TypeScript strict mode (no 'any')
-- hailer.activity.list(workflowId, phaseId, options) - 3 params
-- Access fields via getFieldValue helper with field IDs
-- Simple useEffect pattern (no useCallback/useRef for data loading)
-
-## Deliverables
-
-1. **FIRST**: Fix src/main.tsx with ChakraProvider
-2. Create src/constants.ts with workflow/field IDs
-3. Create src/hooks/ with data fetching hooks
-4. Create src/components/ with UI components
-5. Update src/App.tsx with the dashboard
-
-## Verification
-
-After building, the app should:
-1. Show styled UI (not plain HTML) - confirms ChakraProvider works
-2. Load data without infinite loops - confirms useEffect pattern works
-3. Display field values correctly - confirms field access works
-
-Report back what was created and confirm the 3 checks above pass.
-`
-})
-```
-
-### Why Spawn Is Required
-
-| Current Session | Spawned Agent |
-|-----------------|---------------|
-| Context gets cluttered | Clean, focused context |
-| May forget patterns | Skills pre-loaded |
-| Easier to make mistakes | Follows patterns strictly |
-| Can't see full picture | Dedicated to this task |
-
-### DO NOT Skip This Step
-
-If you catch yourself writing components without spawning, **STOP** and spawn the agent first.