@hailer/mcp 1.1.13 → 1.1.15

package/.claude/skills/hailer-app-builder/SKILL.md

@@ -0,0 +1,1440 @@
+---
+name: hailer-app-builder
+description: Patterns for building Hailer apps with @hailer/app-sdk
+version: 1.3.1
+triggers:
+  - build app
+  - hailer app
+  - app sdk
+---
+
+# Hailer App Builder Skill
+
+Patterns and templates for building Hailer apps with @hailer/app-sdk.
+
+<critical-rules>
+## CRITICAL: Scaffolding and Data Sources
+
+**ALWAYS use scaffold_hailer_app MCP tool** to create new apps. Never manually create the project structure.
+
+### scaffold_hailer_app - One-Shot Full Setup
+
+This tool does EVERYTHING in one call:
+- Scaffolds project from `@hailer/create-app@beta` template (Vite + React + TypeScript)
+- Runs `npm install`
+- Configures CORS in `vite.config.ts`
+- **Reuses existing localhost dev app** if one exists, otherwise creates a new one (with auto-generated icon)
+- Shares app with entire workspace
+- Adds appId to `manifest.json`
+- Starts dev server on port 3000
+
+**NEVER call `create_app` separately during scaffolding — it creates duplicates.** The scaffold tool handles dev app creation/reuse internally.
+
+**Publishing (when ready):** Call `publish_hailer_app` — it builds, packages with correct tar structure (`package/dist/manifest.json`), uploads to S3, and auto-updates app URL to production.
+
+**You're customizing a working starter app**, not building from scratch.
+
+### create_app - Entry Only (No Local Files)
+
+Use `mcp__hailer__create_app` when you:
+- Need a production app entry pointing to a deployed URL
+- Want to register an external/existing app in Hailer
+- Already have app code and just need the Hailer entry
+
+```
+mcp__hailer__create_app({
+  name: "Production App",
+  url: "https://app.example.com"
+})
+```
+
+**scaffold = full development setup**
+**create_app = just the Hailer entry/frame**
+
+**For project data structure (workflows, fields, phases):**
+- READ workspace/ TypeScript files directly (fields.ts, phases.ts, enums.ts)
+- Do NOT use MCP tools for data structure queries
+- The SDK pull provides all needed type information locally
+
+```typescript
+// For app constants, read from local workspace files:
+// - workspace/enums.ts (IDs)
+// - workspace/[Workflow]_[id]/fields.ts (field definitions)
+// - workspace/[Workflow]_[id]/phases.ts (phase definitions)
+```
+</critical-rules>
+
+<local-dev-flow>
+## Development Flow
+
+**Default: Local development.** `scaffold_hailer_app` handles everything automatically:
+1. Creates local project files
+2. Reuses existing localhost dev app (or creates one if none exists) at `http://localhost:3000`
+3. Shares the app with the workspace
+4. Starts the dev server
+
+**Do NOT call `create_app` during scaffolding.** The scaffold tool handles it.
+
+After scaffolding, run `npm run dev` and test inside Hailer iframe.
+
+**Publishing: Only when user explicitly asks.** Load the `publish-hailer-app` skill, which covers manifest validation, file upload via `publish_hailer_app`, and URL switch from localhost to production via `update_app`.
+
+### Manual Local Dev App (Rare Cases)
+
+Only needed if:
+- You have existing code without a dev app entry
+- The scaffold's dev app was deleted
+
+```
+mcp__hailer__create_app({
+  name: "Local Dev",
+  url: "http://localhost:3000",
+  description: "Local development testing"
+})
+```
+
+Or manually in Hailer UI: Apps → Create App → URL: http://localhost:3000
+</local-dev-flow>
+
+<sdk-setup>
+## Hook Import (CRITICAL)
+
+```typescript
+// CORRECT - local default import
+import useHailer from './hailer/use-hailer';
+
+// WRONG - will fail build
+import { useHailer } from '@hailer/app-sdk';
+```
+
+## Hook Usage
+
+```typescript
+function App() {
+  const { inside, hailer } = useHailer();
+
+  // CORRECT dependency array
+  useEffect(() => {
+    // fetch data
+  }, [inside]);  // Use [inside] NOT [hailer]
+
+  // Early return AFTER hooks
+  if (!inside) return <Text>Open this app inside Hailer</Text>;
+
+  return <Box>...</Box>;
+}
+```
+</sdk-setup>
+
+<usehailer-fix>
+## CRITICAL: Replace Scaffold's useHailer Hook
+
+**The scaffold generates a buggy useHailer hook.** After scaffolding, ALWAYS replace `src/hailer/use-hailer.ts` with this shared-state implementation:
+
+### Why the Scaffold's Hook is Broken
+
+The scaffold creates a hook using per-component `useState`:
+
+```typescript
+// ❌ BUGGY - each component gets its own state
+function useHailer() {
+  const [inside, setInside] = useState(false);  // Each component gets separate copy!
+
+  useEffect(() => {
+    hailer.init({ config: () => setInside(true) });  // Only updates THIS component
+  }, []);
+
+  return { inside, hailer };
+}
+```
+
+**Result:** App.tsx sees `inside: true`, but child pages (Dashboard, Settings) still see `inside: false`.
+
+### The Fix: Shared State with useSyncExternalStore
+
+Replace `src/hailer/use-hailer.ts` with:
+
+```typescript
+import { useSyncExternalStore } from 'react';
+import HailerApi from '@hailer/app-sdk';
+
+// Types
+interface HailerState {
+  inside: boolean;
+  hailer: ReturnType<typeof HailerApi> | null;
+  config: Record<string, unknown> | null;
+}
+
+declare global {
+  interface Window {
+    __hailerStore?: {
+      state: HailerState;
+      listeners: Set<() => void>;
+      subscribe: (listener: () => void) => () => void;
+      getSnapshot: () => HailerState;
+      setState: (newState: Partial<HailerState>) => void;
+    };
+  }
+}
+
+// Initialize store once on window
+function getStore() {
+  if (!window.__hailerStore) {
+    window.__hailerStore = {
+      state: { inside: false, hailer: null, config: null },
+      listeners: new Set(),
+      subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+      },
+      getSnapshot() {
+        return this.state;
+      },
+      setState(newState) {
+        this.state = { ...this.state, ...newState };
+        this.listeners.forEach((l) => l());
+      },
+    };
+
+    // Initialize SDK once
+    const api = HailerApi({
+      config: (inside, cfg) => {  // SDK passes (inside: boolean, config: object)
+        window.__hailerStore!.setState({
+          inside: inside,
+          config: cfg?.fields ?? null,
+        });
+      },
+      error: (err) => {
+        console.error('Hailer SDK error:', err);
+      },
+    });
+    window.__hailerStore.setState({ hailer: api });
+  }
+  return window.__hailerStore;
+}
+
+export default function useHailer() {
+  const store = getStore();
+  const state = useSyncExternalStore(
+    store.subscribe.bind(store),
+    store.getSnapshot.bind(store)
+  );
+
+  return {
+    inside: state.inside,
+    hailer: state.hailer!,
+    config: state.config,
+  };
+}
+```
+
+### Why This Works
+
+1. **Single store on `window`** - All components share one source of truth
+2. **SDK initialized once** - No duplicate callbacks
+3. **useSyncExternalStore** - React 18's official pattern for external state
+4. **All components update together** - When `inside` changes, every subscriber re-renders
+
+### Giuseppe Rule
+
+After `scaffold_hailer_app`, ALWAYS replace `src/hailer/use-hailer.ts` with the shared-state version above.
+</usehailer-fix>
+
+<sdk-api>
+## Activity API
+
+```typescript
+// List activities from workflow phase
+const activities = await hailer.activity.list(workflowId, phaseId, options?);
+
+// Get single activity
+const activity = await hailer.activity.get(activityId);
+
+// Create activities
+const created = await hailer.activity.create(workflowId, activities[], options?);
+
+// Update activities (returns count)
+const count = await hailer.activity.update(activities[], options);
+
+// Remove activities (returns count)
+const count = await hailer.activity.remove(activityIds[]);
+```
+
+### ActivityListOptions
+
+```typescript
+interface ActivityListOptions {
+  sortBy?: 'name' | 'created' | 'updated' | 'following' | 'owner' | 'team' | 'completedOn' | 'priority';
+  sortOrder?: 'asc' | 'desc';
+  limit?: number;
+  skip?: number;
+  includeUsers?: boolean;
+  includeTeams?: boolean;
+  includeHistory?: boolean;
+  filters?: any;
+}
+```
+
+### ActivityCreateOptions
+
+```typescript
+interface ActivityCreateOptions {
+  teamId?: string;           // Assign to team
+  fileIds?: string[];        // Attach files (use ui.files.uploadFile first)
+  followerIds?: string[];    // Add followers
+  location?: {
+    label?: string;
+    type: 'area' | 'point' | 'polyline';
+    data: [{ lat: number; lng: number }];
+  };
+  discussionId?: string;     // Link to discussion
+  phaseId?: string;          // Initial phase (defaults to first)
+  returnDocument?: boolean;  // Return full activity after create
+  ignoreRequired?: boolean;  // Skip required field validation
+}
+```
+
+### Activity Interface
+
+```typescript
+interface Activity {
+  _id: string;
+  name: string;
+  process: string;
+  currentPhase: string;
+  fields?: Record<string, { value: unknown }>;
+  files?: string[];
+  followers?: string[];
+  created?: number;
+  updated?: number;
+  updatedBy?: string;
+  priority?: number;
+  location?: {
+    type: 'point' | 'area' | 'polyline';
+    label: string | null;
+    data: Array<{ lat: number; lng: number }>;
+  };
+}
+```
+
+### Phase Transitions (Moving Activities Between Phases)
+
+**CRITICAL:** The SDK does NOT have a `hailer.activity.move()` method. To move activities between phases, use `hailer.activity.update()` with the `phaseId` parameter.
+
+```typescript
+// CORRECT - Use activity.update() with phaseId
+await hailer.activity.update([
+  {
+    _id: activityId,
+    phaseId: newPhaseId,  // Move to different phase
+  },
+], {});
+
+// ❌ WRONG - activity.move() DOES NOT EXIST
+// await hailer.activity.move(activityId, newPhaseId);  // This method doesn't exist in the SDK!
+```
+
+**Example: Move multiple activities to new phase**
+```typescript
+const activityIds = ['id1', 'id2', 'id3'];
+const targetPhaseId = 'phaseId789';
+
+await hailer.activity.update(
+  activityIds.map(id => ({
+    _id: id,
+    phaseId: targetPhaseId,
+  })),
+  {}
+);
+```
+
+### CRITICAL: activity.list() Requires Valid phaseId
+
+**Problem:** `hailer.activity.list(workflowId, '', options)` fails - empty phaseId not allowed.
+
+**Solution:** Query all phases in parallel:
+```typescript
+const ALL_PHASES = ['phaseId1', 'phaseId2', 'phaseId3'];
+
+const phaseResults = await Promise.all(
+  ALL_PHASES.map((phaseId) =>
+    hailer.activity.list(workflowId, phaseId, { limit: 500 }).catch(() => [])
+  )
+);
+const allActivities = phaseResults.flat();
+```
+
+### Phase Selection: Which Phases to Fetch
+
+**Don't blindly fetch all phases.** Consider what the user needs to see:
+
+| App Type | Phases to Fetch | Rationale |
+|----------|-----------------|-----------|
+| Sales dashboard | Active only | Don't show internal drafts |
+| Product manager view | Draft + Active | Need to see work-in-progress |
+| Archive browser | Archived only | Historical data |
+| Kanban board | All except Archived | Full workflow visibility |
+
+**Example: Role-based phase selection**
+```typescript
+// Define phases per user role
+const PHASE_CONFIG = {
+  sales: ['activePhaseId'],
+  manager: ['draftPhaseId', 'activePhaseId'],
+  admin: ['draftPhaseId', 'activePhaseId', 'archivedPhaseId'],
+};
+
+// Fetch based on role
+const userRole = 'sales';  // from app config or user check
+const phases = PHASE_CONFIG[userRole] || PHASE_CONFIG.sales;
+
+const results = await Promise.all(
+  phases.map(phaseId => hailer.activity.list(workflowId, phaseId))
+);
+```
+
+**Document phase selection in PRD:**
+```markdown
+## Data Access
+- **Product Browser**: Shows Draft + Active phases (managers need WIP visibility)
+- **Public Dashboard**: Active only (no internal data exposed)
+- **Insights**: Active only (accurate counts, no duplicates from drafts)
+```
+
+## Kanban API
+
+```typescript
+// List activities grouped by phase (kanban view)
+const kanban = await hailer.activity.kanban.list(workflowId, options?);
+// Returns: { map: { [phaseId]: { activities: [...], meta: { count, ... } } } }
+
+// Load single activity in kanban format
+const item = await hailer.activity.kanban.load(activityId);
+// Returns: { activity: {...}, process: string, phase: string }
+
+// Update activity priority
+await hailer.activity.kanban.updatePriority(activityId, priority);
+```
+
+### KanbanListOptions
+
+```typescript
+interface ActivityKanbanListOptions {
+  filter: {
+    user?: { uid: string; field: string };
+    account?: string;
+    team?: string;
+    dates?: { field: string; start: number; end: number };
+  };
+  search?: string;
+  limit?: number;
+  skip?: number;
+  phase?: string;
+  includeUsers?: boolean;
+  includeTeams?: boolean;
+}
+```
+
+## UI API
+
+### Activity UI
+
+```typescript
+// Open activity in sidebar
+await hailer.ui.activity.open(activityId, options?);
+
+type ActivityTabTypes = 'detail' | 'discussion' | 'files' | 'location' | 'linkedFrom' | 'options';
+
+// Open with specific tab
+await hailer.ui.activity.open(activityId, { tab: 'files' });
+
+// Open create form (returns created activity or null if cancelled)
+const result = await hailer.ui.activity.create(workflowId, {
+  name?: string,
+  fields?: { [fieldId]: value },
+  location?: { type: 'point', data: [{ lat, lng }] }
+});
+
+// Bulk edit multiple activities
+await hailer.ui.activity.editMultiple(activityIds[]);
+```
+
+**Note:** `hailer.openSidebar()` does NOT exist - use `hailer.ui.activity.open()`.
+
+### File Upload
+
+```typescript
+// Upload file to Hailer (returns file ID)
+const fileId = await hailer.ui.files.uploadFile(
+  file,      // File object from <input type="file">
+  filename,  // Desired filename
+  { isPublic?: boolean }
+);
+
+// Then attach to activity on create:
+await hailer.activity.create(workflowId, [{ name: 'Doc' }], { fileIds: [fileId] });
+```
+
+### Snackbar (Toast Notifications)
+
+```typescript
+// Show notification
+await hailer.ui.snackbar.open(text, buttonLabel, duration?);
+
+// Examples
+hailer.ui.snackbar.open('Saved!', 'OK');
+hailer.ui.snackbar.open('Deleted', 'Undo', 5000);
+```
+
+### Insight UI
+
+```typescript
+await hailer.ui.insight.create(workspaceId?);  // Open create dialog
+await hailer.ui.insight.edit(insightId);       // Open edit dialog
+await hailer.ui.insight.delete(insightId);     // Open delete confirmation
+await hailer.ui.insight.permission(insightId); // Open permissions dialog
+```
+
+## Insight API
+
+```typescript
+// Get insight data (SQL query results)
+const data = await hailer.insight.data(insightId, { update?: true });
+
+// List all insights
+const insights = await hailer.insight.list();
+
+// Update insight
+const updated = await hailer.insight.update(insightId, partialUpdate);
+```
+
+**Response structure:**
+```typescript
+interface InsightData {
+  columns: string[];
+  rows: any[][];
+}
+
+interface InsightDoc {
+  _id: string;
+  name: string;
+  // ... other insight properties
+}
+```
+
+## Workflow API
+
+```typescript
+// List all workflows
+const workflows = await hailer.workflow.list();
+
+// Get single workflow with full schema
+const workflow = await hailer.workflow.get(workflowId);
+```
+
+## User API
+
+```typescript
+// Get current logged-in user
+const me = await hailer.user.current();
+// Returns: { _id, email, firstname, lastname, ... }
+
+// Get specific user by ID
+const user = await hailer.user.get(userId);
+
+// List all workspace users (returns object keyed by user ID)
+const users = await hailer.user.list();
+```
+
+### Getting User Info for Personalized Greeting
+
+**The config callback does NOT include user info:**
+```typescript
+// ❌ WRONG - config only has { fields: {} }
+const { config } = useHailer();
+const userName = config?.userName;  // undefined!
+```
+
+**Use hailer.user.current() instead:**
+```typescript
+const { inside, hailer } = useHailer();
+const [userName, setUserName] = useState<string>('');
+
+useEffect(() => {
+  if (!inside) return;
+
+  hailer.user.current().then(user => {
+    setUserName(user.firstname || 'there');
+  });
+}, [inside]);
+
+return <Heading>Hello, {userName}!</Heading>;
+```
+
+## Workspace API
+
+```typescript
+// Get current workspace
+const workspace = await hailer.workspace.current();
+
+// List workspaces (personal apps only)
+const workspaces = await hailer.workspace.list();
+```
+</sdk-api>
+
+<field-patterns>
+## Extracting Field Values
+
+```typescript
+// Fields are optional and nested
+interface Activity {
+  fields?: Record<string, { value: unknown }>;
+}
+
+// Safe extraction helper
+function getFieldValue<T>(activity: Activity, fieldId: string, defaultValue: T): T {
+  return (activity.fields?.[fieldId]?.value as T) ?? defaultValue;
+}
+
+// Usage
+const name = getFieldValue(activity, 'fieldId123', '');
+const count = getFieldValue(activity, 'fieldId456', 0);
+const date = getFieldValue(activity, 'fieldId789', null);
+```
+
+## Field Types
+
+```typescript
+// Text field
+const text = activity.fields?.['fieldId']?.value as string;
+
+// Number field
+const num = activity.fields?.['fieldId']?.value as number;
+
+// Date field (timestamp)
+const date = activity.fields?.['fieldId']?.value as number;
+const formatted = new Date(date).toLocaleDateString();
+
+// Enum/Select field
+const status = activity.fields?.['fieldId']?.value as string;
+
+// ActivityLink field (reference to another activity)
+// IMPORTANT: ActivityLink has nested structure, not direct values
+interface ActivityLinkValue {
+  _id: string;
+  name: string;
+}
+const linked = activity.fields?.['fieldId']?.value as ActivityLinkValue;
+const linkedId = linked?._id;      // Get linked activity ID
+const linkedName = linked?.name || 'Unknown';  // Get display name
+
+// User field
+interface UserValue {
+  _id: string;
+  firstname: string;
+  lastname: string;
+}
+const user = activity.fields?.['fieldId']?.value as UserValue;
+const userName = user ? `${user.firstname} ${user.lastname}` : 'Unknown';
+```
+
+## Finnish Date Parsing
+
+Insights and some fields return Finnish date strings (`dd.mm.yyyy`) instead of timestamps. These can't be sorted directly.
+
+```typescript
+// ❌ WRONG - Number("03.02.2026") returns NaN
+dates.sort((a, b) => Number(a) - Number(b));
+
+// ✅ CORRECT - Parse Finnish dates to Date objects
+function parseFinnishDate(dateStr: string): Date | null {
+  // Matches "03.02.2026" or "03.02.2026 10:00"
+  const match = dateStr.match(/^(\d{1,2})\.(\d{1,2})\.(\d{4})(?:\s+(\d{1,2}):(\d{2}))?/);
+  if (!match) return null;
+
+  const [, day, month, year, hours = '0', minutes = '0'] = match;
+  return new Date(
+    parseInt(year),
+    parseInt(month) - 1,  // JS months are 0-indexed
+    parseInt(day),
+    parseInt(hours),
+    parseInt(minutes)
+  );
+}
+
+// Sorting Finnish dates
+items.sort((a, b) => {
+  const dateA = parseFinnishDate(a.dateField);
+  const dateB = parseFinnishDate(b.dateField);
+  if (!dateA || !dateB) return 0;
+  return dateA.getTime() - dateB.getTime();
+});
+
+// Formatting back to Finnish
+function formatFinnishDate(date: Date): string {
+  return date.toLocaleDateString('fi-FI');  // "3.2.2026"
+}
+
+function formatFinnishDateTime(date: Date): string {
+  return date.toLocaleString('fi-FI', {
+    day: 'numeric',
+    month: 'numeric',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });  // "3.2.2026 klo 10.00"
+}
+```
+
+**When to use:**
+- Insight data returns formatted dates (not timestamps)
+- Text fields containing dates
+- Displaying dates to Finnish users
+</field-patterns>
+
+<component-templates>
+## Activity Table
+
+```typescript
+import { Table, Thead, Tbody, Tr, Th, Td, Box, Spinner, Text } from '@chakra-ui/react';
+
+interface Activity {
+  _id: string;
+  name: string;
+  fields?: Record<string, { value: unknown }>;
+}
+
+interface Props {
+  activities: Activity[];
+  loading: boolean;
+  columns: { fieldId: string; label: string }[];
+}
+
+function ActivityTable({ activities, loading, columns }: Props) {
+  if (loading) return <Spinner />;
+  if (activities.length === 0) return <Text>No data</Text>;
+
+  return (
+    <Table variant="simple" size="sm">
+      <Thead>
+        <Tr>
+          <Th>Name</Th>
+          {columns.map(col => (
+            <Th key={col.fieldId}>{col.label}</Th>
+          ))}
+        </Tr>
+      </Thead>
+      <Tbody>
+        {activities.map(activity => (
+          <Tr key={activity._id}>
+            <Td>{activity.name}</Td>
+            {columns.map(col => (
+              <Td key={col.fieldId}>
+                {String(activity.fields?.[col.fieldId]?.value ?? '-')}
+              </Td>
+            ))}
+          </Tr>
+        ))}
+      </Tbody>
+    </Table>
+  );
+}
+```
+
+## Activity Card
+
+```typescript
+import { Box, Heading, Text, VStack, useColorModeValue } from '@chakra-ui/react';
+
+interface Props {
+  activity: Activity;
+  fieldId: string;
+  fieldLabel: string;
+}
+
+function ActivityCard({ activity, fieldId, fieldLabel }: Props) {
+  const bg = useColorModeValue('white', 'gray.700');
+  const borderColor = useColorModeValue('gray.200', 'gray.600');
+
+  return (
+    <Box
+      p={4}
+      bg={bg}
+      borderRadius="md"
+      border="1px"
+      borderColor={borderColor}
+    >
+      <VStack align="start" spacing={2}>
+        <Heading size="sm">{activity.name}</Heading>
+        <Text fontSize="sm" color="gray.500">
+          {fieldLabel}: {String(activity.fields?.[fieldId]?.value ?? '-')}
+        </Text>
+      </VStack>
+    </Box>
+  );
+}
+```
+
+## Stats Card
+
+```typescript
+import { Stat, StatLabel, StatNumber, StatHelpText, Box, useColorModeValue } from '@chakra-ui/react';
+
+interface Props {
+  label: string;
+  value: number | string;
+  helpText?: string;
+}
+
+function StatsCard({ label, value, helpText }: Props) {
+  const bg = useColorModeValue('white', 'gray.700');
+
+  return (
+    <Box p={4} bg={bg} borderRadius="md" shadow="sm">
+      <Stat>
+        <StatLabel>{label}</StatLabel>
+        <StatNumber>{value}</StatNumber>
+        {helpText && <StatHelpText>{helpText}</StatHelpText>}
+      </Stat>
+    </Box>
+  );
+}
+```
+</component-templates>
+
+<app-template>
+## Full App Template
+
+```typescript
+import { useEffect, useState } from 'react';
+import {
+  Box,
+  Heading,
+  Text,
+  Spinner,
+  Table,
+  Thead,
+  Tbody,
+  Tr,
+  Th,
+  Td,
+  VStack,
+  useColorModeValue,
+} from '@chakra-ui/react';
+import useHailer from './hailer/use-hailer';
+
+// Field IDs from workflow schema (provided by orchestrator)
+const FIELDS = {
+  NAME_FIELD: 'fieldId123',
+  STATUS_FIELD: 'fieldId456',
+} as const;
+
+interface Activity {
+  _id: string;
+  name: string;
+  fields?: Record<string, { value: unknown }>;
+}
+
+function App() {
+  const { inside, hailer } = useHailer();
+  const [activities, setActivities] = useState<Activity[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const bg = useColorModeValue('gray.50', 'gray.800');
+
+  // Fetch data when inside Hailer
+  useEffect(() => {
+    if (!inside) return;
+
+    async function fetchData() {
+      try {
+        setLoading(true);
+        const data = await hailer.activity.list(
+          'workflowId',  // Replace with actual workflow ID
+          'phaseId',      // Replace with actual phase ID
+          { limit: 100 }
+        );
+        setActivities(data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to load data');
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    fetchData();
+  }, [inside]);  // IMPORTANT: [inside] not [hailer]
+
+  // Early return AFTER hooks
+  if (!inside) {
+    return (
+      <Box p={8} textAlign="center">
+        <Text>Please open this app inside Hailer</Text>
+      </Box>
+    );
+  }
+
+  if (loading) {
+    return (
+      <Box p={8} textAlign="center">
+        <Spinner size="xl" />
+      </Box>
+    );
+  }
+
+  if (error) {
+    return (
+      <Box p={8} textAlign="center">
+        <Text color="red.500">{error}</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box p={4} bg={bg} minH="100vh">
+      <VStack spacing={4} align="stretch">
+        <Heading size="lg">Dashboard</Heading>
+
+        <Table variant="simple" size="sm">
+          <Thead>
+            <Tr>
+              <Th>Name</Th>
+              <Th>Status</Th>
+            </Tr>
+          </Thead>
+          <Tbody>
+            {activities.map(activity => (
+              <Tr key={activity._id}>
+                <Td>{activity.name}</Td>
+                <Td>{String(activity.fields?.[FIELDS.STATUS_FIELD]?.value ?? '-')}</Td>
+              </Tr>
+            ))}
+          </Tbody>
+        </Table>
+      </VStack>
+    </Box>
+  );
+}
+
+export default App;
+```
+</app-template>
+
+<theme-patterns>
+## Hailer Theme Colors
+
+```typescript
+// Dark mode support - ALWAYS use useColorModeValue
+const bg = useColorModeValue('white', 'gray.700');
+const borderColor = useColorModeValue('gray.200', 'gray.600');
+const textColor = useColorModeValue('gray.800', 'white');
+const mutedColor = useColorModeValue('gray.500', 'gray.400');
+
+// Valid color tokens (DO NOT invent tokens)
+// gray.50, gray.100, ..., gray.900
+// white, black
+// red.500, green.500, blue.500, yellow.500, purple.500
+```
+
+## Light/Dark Mode Safety Rules
+
+**DON'T use these patterns:**
+```typescript
+// ❌ WRONG - brand colors may not be defined in theme
+color="brand.600"
+
+// ❌ WRONG - hard-coded white fails on light backgrounds
+<Text color="white">Always white</Text>
+
+// ❌ WRONG - assumes light mode background
+<Badge bg="blue.100" color="blue.800">Status</Badge>
+```
+
+**DO use these patterns:**
+```typescript
+// ✅ CORRECT - explicit colors that exist in Chakra
+color="blue.600"
+
+// ✅ CORRECT - adapts to color mode
+<Text color={useColorModeValue('gray.800', 'white')}>Adapts</Text>
+
+// ✅ CORRECT - badge adapts to mode
+const badgeBg = useColorModeValue('blue.100', 'blue.700');
+const badgeColor = useColorModeValue('blue.800', 'blue.100');
+<Badge bg={badgeBg} color={badgeColor}>Status</Badge>
+```
+
+**Semantic tokens (define once, use everywhere):**
+```typescript
+// In theme.ts extendTheme
+semanticTokens: {
+  colors: {
+    appBg: { _light: 'gray.50', _dark: 'gray.800' },
+    cardBg: { _light: 'white', _dark: 'gray.700' },
+    textPrimary: { _light: 'gray.800', _dark: 'white' },
+    textMuted: { _light: 'gray.500', _dark: 'gray.400' },
+  }
+}
+
+// Usage - no useColorModeValue needed
+<Box bg="appBg"><Text color="textPrimary">Clean!</Text></Box>
+```
+
+## Phase-Colored Badges and Bars
+
+When displaying phase/status colors that need to work in both modes:
+
+```typescript
+import { useColorMode } from '@chakra-ui/react';
+
+// Helper for phase-colored elements
+function usePhaseColors(baseColor: string) {
+  const { colorMode } = useColorMode();
+
+  if (colorMode === 'light') {
+    return {
+      bg: `${baseColor}.100`,
+      color: `${baseColor}.800`,
+      borderColor: `${baseColor}.200`,
+    };
+  } else {
+    return {
+      bg: `${baseColor}.700`,
+      color: `${baseColor}.100`,
+      borderColor: `${baseColor}.600`,
+    };
+  }
+}
+
+// Usage
+function PhaseBadge({ phase, color }: { phase: string; color: string }) {
+  const colors = usePhaseColors(color);
+
+  return (
+    <Badge bg={colors.bg} color={colors.color}>
+      {phase}
+    </Badge>
+  );
+}
+
+// Event bar with phase color
+function EventBar({ title, phaseColor }: { title: string; phaseColor: string }) {
+  const colors = usePhaseColors(phaseColor);
+
+  return (
+    <Box
+      px={2}
+      py={1}
+      bg={colors.bg}
+      color={colors.color}
+      borderLeft="3px solid"
+      borderLeftColor={colors.borderColor}
+      borderRadius="sm"
+    >
+      {title}
+    </Box>
+  );
+}
+```
+
+**Color mapping from Hailer phases:**
+```typescript
+// Map Hailer phase colors to Chakra color names
+const PHASE_COLOR_MAP: Record<string, string> = {
+  'blue': 'blue',
+  'green': 'green',
+  'red': 'red',
+  'yellow': 'yellow',
+  'purple': 'purple',
+  'orange': 'orange',
+  'gray': 'gray',
+};
+```
+
+## Common UI Patterns
+
+```typescript
+// Page container
+<Box p={4} bg={useColorModeValue('gray.50', 'gray.800')} minH="100vh">
+
+// Card
+<Box p={4} bg={useColorModeValue('white', 'gray.700')} borderRadius="md" shadow="sm">
+
+// Section with border
+<Box p={4} border="1px" borderColor={useColorModeValue('gray.200', 'gray.600')} borderRadius="md">
+```
+</theme-patterns>
+
+<troubleshooting>
+## Workflow Permission Errors
+
+When SDK calls fail with permission/not-allowed errors, check **workflow configuration in Hailer** first.
+
+**Common symptoms:**
+- `hailer.activity.move()` fails with permission error
+- Phase transitions not working
+- "Not allowed" errors on operations that should work
+
+**Cause:** Features like phase transitions must be **enabled in workflow configuration** in Hailer. The SDK can't do operations that aren't configured.
+
+**Debug steps:**
+1. Check Hailer UI: Workflow Settings → Phase settings
+2. Verify phase transitions are configured (`possibleNextPhase`)
+3. Verify user has permission to the workflow/phase
+4. Check if the feature (move, archive, etc.) is enabled for that phase
+
+**Example:** Phase move fails because `possibleNextPhase` doesn't include the target phase.
+</troubleshooting>
+
+<build-fixes>
+## Common Build Errors
+
+### Cannot find module '@hailer/app-sdk'
+```typescript
+// WRONG
+import { useHailer } from '@hailer/app-sdk';
+
+// CORRECT
+import useHailer from './hailer/use-hailer';
+```
+
+### has no exported member 'useHailer'
+```typescript
+// WRONG - named import
+import { useHailer } from './hailer/use-hailer';
+
+// CORRECT - default import
+import useHailer from './hailer/use-hailer';
+```
+
+### fields possibly undefined
+```typescript
+// WRONG
+const value = activity.fields[fieldId].value;
+
+// CORRECT
+const value = activity.fields?.[fieldId]?.value;
+```
+
+### Infinite re-render loop
+```typescript
+// WRONG - hailer changes every render
+useEffect(() => { ... }, [hailer]);
+
+// CORRECT - inside is stable
+useEffect(() => { ... }, [inside]);
+```
+
+### Hooks order error
+```typescript
+// WRONG - early return before hook
+if (!inside) return <Text>Error</Text>;
+const [data, setData] = useState([]);  // Error!
+
+// CORRECT - hooks first, then early return
+const [data, setData] = useState([]);
+if (!inside) return <Text>Error</Text>;
+```
+
+### Hooks inside map() or conditionals
+```typescript
+// WRONG - hook in map
+{items.map((item) => (
+  <Tr _hover={{ bg: useColorModeValue('gray.50', 'gray.600') }}>
+))}
+
+// CORRECT - hook at top level
+const hoverBg = useColorModeValue('gray.50', 'gray.600');
+{items.map((item) => (
+  <Tr _hover={{ bg: hoverBg }}>
+))}
+```
+
+### hailer.activity.move is not a function
+```typescript
+// ❌ WRONG - activity.move() DOES NOT EXIST (common mistake)
+// await hailer.activity.move(activityId, newPhaseId);  // This will fail!
+
+// CORRECT - use activity.update() with phaseId
+await hailer.activity.update([
+  {
+    _id: activityId,
+    phaseId: newPhaseId,
+  },
+], {});
+```
+
+**Explanation:** Phase transitions in Hailer are done via the `update()` method by setting the `phaseId` field. There is no separate `move()` method in the SDK.
+
+### Routing: HashRouter vs BrowserRouter
+
+**Most Hailer apps don't need routing at all.** Use state-based page switching:
+```typescript
+const [page, setPage] = useState('home');
+{page === 'home' && <HomePage />}
+{page === 'settings' && <SettingsPage />}
+```
+
+**If you need routing** (bookmarkable URLs, back button, public apps):
+```typescript
+// ✅ USE HashRouter - works in iframe, no server config
+import { createHashRouter, RouterProvider } from 'react-router-dom';
+
+const router = createHashRouter([
+  { path: '/', element: <HomePage /> },
+  { path: '/settings', element: <SettingsPage /> },
+]);
+
+// URLs look like: yourapp.com/#/settings
+```
+
+```typescript
+// ⚠️ AVOID BrowserRouter in iframe apps
+// Can cause "No routes matched location /index.html" errors
+// because iframe URL contains /index.html path
+```
+
+**When to use routing:**
+- Public apps with shareable URLs
+- Complex multi-section apps (like hailer-admin)
+- Apps where back button navigation matters
+</build-fixes>
+
+<sdk-crud>
+## SDK Create/Update Formats
+
+### activity.create() Format
+
+**Signature:** `hailer.activity.create(workflowId, activities[], options)`
+
+**CRITICAL:** Takes array of activities, raw field values (not wrapped).
+
+```typescript
+await hailer.activity.create(WORKFLOW_ID, [
+  {
+    name: 'Activity name',
+    fields: {
+      [FIELD_ID]: 'string or number value',  // NOT wrapped in { value: ... }
+      [ACTIVITYLINK_FIELD]: 'linkedActivityId',  // Just the ID, not { _id, name }
+    },
+  },
+], {});
+```
+
+**Common mistakes:**
+- Passing single object instead of array
+- Wrapping field values in `{ value: ... }`
+- Passing `{ _id, name }` for activitylinks instead of just ID
+
+### activity.update() Format
+
+**Signature:** `hailer.activity.update(activities[], options)`
+
+```typescript
+await hailer.activity.update([
+  {
+    _id: 'activityId',
+    name: 'New name',  // optional
+    fields: {
+      [FIELD_ID]: newValue,
+    },
+    phaseId: 'newPhaseId',  // optional - move to different phase
+  },
+], {});
+```
+</sdk-crud>
+
+<file-structure>
+## Required Files
+
+```
+src/
+  App.tsx           # Main component (EDIT THIS)
+  main.tsx          # Entry point (NEVER EDIT)
+  hailer/
+    use-hailer.ts   # SDK hook (generated)
+  types/
+    index.ts        # Type definitions (CREATE)
+  utils/
+    fields.ts       # Field helpers (CREATE)
+  constants/
+    fields.ts       # Field ID constants (CREATE)
+```
+
+## Constants File Pattern
+
+```typescript
+// src/constants/fields.ts
+export const WORKFLOW_ID = 'workflowId123';
+export const PHASE_ID = 'phaseId456';
+
+export const FIELDS = {
+  NAME: 'fieldId001',
+  STATUS: 'fieldId002',
+  DATE: 'fieldId003',
+} as const;
+```
+
+## Types File Pattern
+
+```typescript
+// src/types/index.ts
+export interface Activity {
+  _id: string;
+  name: string;
+  fields?: Record<string, { value: unknown }>;
+  created?: number;
+  updated?: number;
+}
+
+export interface ActivityLinkValue {
+  _id: string;
+  name: string;
+}
+
+export interface UserValue {
+  _id: string;
+  firstname: string;
+  lastname: string;
+}
+```
+</file-structure>
+
+<app-manifest>
+## App Manifest Configuration
+
+The `manifest.json` file in app root defines configurable settings exposed in Hailer UI.
+
+### config.fields Structure
+
+```json
+{
+  "name": "My App",
+  "version": "1.0.0",
+  "config": {
+    "fields": {
+      "defaultView": {
+        "type": "string",
+        "label": "Default View",
+        "default": "month"
+      },
+      "slotMinTime": {
+        "type": "string",
+        "label": "Day Start Time",
+        "default": "08:00"
+      },
+      "showWeekends": {
+        "type": "boolean",
+        "label": "Show Weekends",
+        "default": true
+      },
+      "itemsPerPage": {
+        "type": "number",
+        "label": "Items Per Page",
+        "default": 25
+      },
+      "enabledFeatures": {
+        "type": "array",
+        "label": "Enabled Features",
+        "default": ["search", "export"]
+      }
+    }
+  }
+}
+```
+
+### Field Types
+
+| Type | Description | Example Default |
+|------|-------------|-----------------|
+| `string` | Text value | `"month"` |
+| `number` | Numeric value | `25` |
+| `boolean` | True/false toggle | `true` |
+| `array` | List of values | `["a", "b"]` |
+
+### Accessing Config in App
+
+Config values come through HailerApi callback when app loads inside Hailer:
+
+```typescript
+const { inside, hailer, config } = useHailer();
+
+// Access configured values
+const defaultView = config?.defaultView ?? 'month';
+const showWeekends = config?.showWeekends ?? true;
+```
+
+### Best Practices
+
+**DO expose in config.fields:**
+- User-customizable options (default views, display preferences)
+- Workflow/phase IDs that vary per installation
+- Feature toggles
+
+**DON'T expose in config.fields:**
+- Values hardcoded in app code (wastes config UI space)
+- Sensitive data (use environment variables)
+- Internal constants that users shouldn't change
+
+**RULE:** If a config field is defined but the app ignores it, remove it from manifest.
+</app-manifest>
+
+<public-api>
+## Public API (Apps Outside Hailer)
+
+For apps that run standalone (outside Hailer iframe) without authentication:
+
+```typescript
+// Public insight data
+const data = await hailer.public.insight.data(insightKey);
+const objects = await hailer.public.insight.dataAsObject(insightKey);
+
+// Public forms
+const formData = await hailer.public.form.data(formsKey);
+const result = await hailer.public.form.submit(formsKey, formData);
+
+// Public app config
+const config = await hailer.public.app.config();
+
+// Public products
+const products = await hailer.public.product.list(filter?, options?);
+const product = await hailer.public.product.get(productId);
+```
+
+**When to use Public API:**
+- Building external-facing apps (not in Hailer iframe)
+- Public dashboards using insight keys
+- Public form submissions
+- No user authentication available
+
+**Note:** Public APIs use keys (not IDs) and don't require authentication.
+</public-api>
+
+<sdk-reference>
+## SDK Type Definitions (For Edge Cases)
+
+The skill covers common SDK methods. For less common APIs, read the type definitions in any Hailer app project:
+
+```
+node_modules/@hailer/app-sdk/lib/modules/
+├── activity.d.ts       - list, get, create, update, remove
+├── activity/kanban.d.ts - kanban.list, load, updatePriority
+├── user.d.ts           - current, get, list
+├── ui.d.ts             - snackbar, activity, insight, files
+├── ui/activity.d.ts    - open, create, editMultiple
+├── ui/snackbar.d.ts    - open
+├── ui/files.d.ts       - uploadFile
+├── insight.d.ts        - data, list, update
+├── process.d.ts        - list, get (workflow API uses this)
+├── workspace.d.ts      - current, list, product methods
+├── permission.d.ts     - map
+├── app.d.ts            - config.update, product methods
+└── public/             - insight, form, product (no auth)
+```
+
+**When to check types:**
+- Method not documented here → read the relevant `.d.ts` file
+- Need method signature details → types are the source of truth
+- New SDK version → types show what's available
+</sdk-reference>