@hailer/mcp 1.1.11 → 1.1.13

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

@@ -1,1434 +0,0 @@
----
-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 template (Vite + React + TypeScript)
-- Runs `npm install`
-- Configures CORS in `vite.config.ts`
-- **Creates dev app entry in Hailer** (with auto-generated icon)
-- Shares app with entire workspace
-- Adds appId to `manifest.json`
-- Starts dev server on port 3000
-
-**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. Creates a dev app entry in Hailer at `http://localhost:3000`
-3. Shares the app with the workspace
-4. Starts the dev server
-
-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>