@hailer/mcp 1.0.29 → 1.1.2

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

@@ -1,12 +1,95 @@
 ---
 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)
 
@@ -37,40 +120,400 @@ function App() {
 ```
 </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, {
-  limit: 100,
-  fields: ['fieldId1', 'fieldId2'],  // Optional: specific fields only
-});
+const activities = await hailer.activity.list(workflowId, phaseId, options?);
 
 // Get single activity
 const activity = await hailer.activity.get(activityId);
 
-// Activity structure
+// 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.get(insightId, { update: true });
+const data = await hailer.insight.data(insightId, { update?: true });
+
+// List all insights
+const insights = await hailer.insight.list();
 
-// Response structure
-interface InsightResponse {
+// 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
@@ -79,9 +522,58 @@ interface InsightResponse {
 // List all workflows
 const workflows = await hailer.workflow.list();
 
-// Get single workflow
+// 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>
@@ -121,12 +613,14 @@ const formatted = new Date(date).toLocaleDateString();
 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 linkedName = linked?.name || 'Unknown';
+const linkedId = linked?._id;      // Get linked activity ID
+const linkedName = linked?.name || 'Unknown';  // Get display name
 
 // User field
 interface UserValue {
@@ -137,6 +631,59 @@ interface UserValue {
 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>
@@ -372,7 +919,7 @@ export default App;
 ## Hailer Theme Colors
 
 ```typescript
-// Dark mode support
+// 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');
@@ -384,6 +931,121 @@ const mutedColor = useColorModeValue('gray.500', 'gray.400');
 // 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
@@ -398,6 +1060,27 @@ const mutedColor = useColorModeValue('gray.500', 'gray.400');
 ```
 </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
 
@@ -447,8 +1130,115 @@ const [data, setData] = useState([]);  // Error!
 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
 
@@ -504,3 +1294,141 @@ export interface UserValue {
 }
 ```
 </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>