@hailer/mcp 1.1.16 → 1.1.17-beta.0

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

@@ -15,41 +15,7 @@ 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**
+**ALWAYS use scaffold_hailer_app MCP tool** to create new apps. Never manually create the project structure. Never call `create_app` separately during scaffolding — it creates duplicates.
 
 **For project data structure (workflows, fields, phases):**
 - READ workspace/ TypeScript files directly (fields.ts, phases.ts, enums.ts)
@@ -64,38 +30,6 @@ mcp__hailer__create_app({
 ```
 </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)
 
@@ -364,42 +298,9 @@ const phaseResults = await Promise.all(
 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'],
-};
+### Phase Selection
 
-// 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)
-```
+Don't blindly fetch all phases — fetch only what the user needs to see (e.g., active only for dashboards, all except archived for kanban). For field value formats and phase selection patterns, see the **sdk-activity-patterns** skill.
 
 ## Kanban API
 
@@ -802,125 +703,6 @@ function StatsCard({ label, value, helpText }: Props) {
 ```
 </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
 
@@ -1052,18 +834,6 @@ const PHASE_COLOR_MAP: Record<string, string> = {
 };
 ```
 
-## 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>
@@ -1072,7 +842,6 @@ const PHASE_COLOR_MAP: Record<string, string> = {
 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
 
@@ -1152,20 +921,8 @@ const hoverBg = useColorModeValue('gray.50', 'gray.600');
 ```
 
 ### 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.
+`activity.move()` does not exist. Use `activity.update([{ _id, phaseId }], {})` — see Phase Transitions in sdk-api.
 
 ### Routing: HashRouter vs BrowserRouter
 
@@ -1276,29 +1033,6 @@ export const FIELDS = {
 } 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>

package/.claude/skills/hailer-apps-pictures/SKILL.md

@@ -76,7 +76,7 @@ Create a wrapper component for CORS handling and error states:
 import { Image, ImageProps, Icon } from '@chakra-ui/react';
 import { FaImage } from 'react-icons/fa6';
 import { useState, useEffect } from 'react';
-import { useHailer } from '../hailer/use-hailer';
+import useHailer from '../hailer/use-hailer';
 
 interface HailerImageProps extends Omit<ImageProps, 'src'> {
   hailerImageUrl?: string;
@@ -102,7 +102,7 @@ export const HailerImage = ({
         return;
       }
 
-      if (!hailer?.ready) {
+      if (!hailer?.ready) {  // NOTE: verify .ready exists on SDK type — may need .activity or similar
         setIsLoading(true);
         return;
       }
@@ -237,7 +237,7 @@ const ProductImageCarousel = ({ allPictures, mainImageUrl }: Props) => {
 ```typescript
 // In App.tsx or data fetching hook
 const fetchProducts = async () => {
-  const data = await hailer.api.public.insight.dataAsObject(PRODUCT_INSIGHT_KEY);
+  const data = await hailer.public.insight.dataAsObject(PRODUCT_INSIGHT_KEY);
 
   return data.map(item => ({
     // ... other fields

package/.claude/skills/hailer-design-system/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: hailer-design-system
-description: Chakra UI v2 theme, colors, icons, and component patterns for Hailer apps
-version: 1.0.0
-triggers: Build app, UI components, styling, theme, colors, icons, buttons, forms
+description: Chakra UI v2 theme, colors, icons, and component patterns for Hailer apps. Includes layout, spacing, visual hierarchy, responsive design, empty/loading states.
+version: 2.0.0
+triggers: Build app, UI components, styling, theme, colors, icons, buttons, forms, layout, spacing, hierarchy, responsive, empty state, loading state, design, UI, UX, mockup, dashboard, grid
 ---
 
 # Hailer Design System
@@ -11,6 +11,83 @@ Chakra UI v2 with custom Hailer theme.
 
 **Full reference:** Read `docs/design-system/HAILER_DESIGN_SYSTEM.md` for comprehensive documentation (all icons, all components, full examples).
 
+---
+
+## Design Principles
+
+### Layout
+
+Common layout patterns (use Chakra Flex/Grid to implement):
+
+```
+Dashboard:    [Sidebar 240px] [Main Content flex-1]
+List View:    [Filters 280px] [Table/Cards flex-1]
+Detail View:  [Main 2/3] [Sidebar 1/3]
+Form:         [Labels 1/3] [Inputs 2/3] or stacked on mobile
+```
+
+Grid: 12-column, 1200–1400px max-width, centered. Gutters 16–24px.
+
+### Spacing Scale
+
+| Token | px | Use |
+|-------|----|-----|
+| 1 | 4px | Icon padding |
+| 2 | 8px | Compact (button padding) |
+| 4 | 16px | Default (card padding, list gaps) |
+| 6 | 24px | Section gaps |
+| 8 | 32px | Page sections |
+| 12 | 48px | Major sections |
+
+### Visual Hierarchy
+
+**Size scale:**
+
+| Level | Size | Weight |
+|-------|------|--------|
+| Page title | 32–48px (`2xl`) | Bold |
+| Section header | 24–28px (`xl`) | Semibold |
+| Card title | 18–20px (`lg`/`md`) | Medium |
+| Body | 14–16px | Regular |
+| Caption/label | 12–13px (`sm`) | Regular/Medium |
+
+**Emphasis:** size > weight > color > whitespace > position (F-pattern: top-left reads first).
+
+**Density:** Bold labels + regular values for scannability. Group related info in cards. Show summary first, details on demand.
+
+### Responsive Breakpoints
+
+| Breakpoint | Width | Layout |
+|------------|-------|--------|
+| Mobile | < 640px | 1 column, stacked |
+| Tablet | 640–1024px | 2 columns, sidebar hidden |
+| Desktop | > 1024px | Full layout |
+| Wide | > 1440px | max-width container |
+
+Mobile adaptations: stack layouts vertically, hamburger menu, 44px min touch targets, bottom sheets over modals.
+
+### Empty States
+
+Always design for empty — never leave a blank panel:
+
+```
+[Illustration / Icon]
+  No items yet
+  Add your first item
+    [+ Add Item]
+```
+
+Use `VStack` centered in the container with muted icon, `Text` heading, helper text, and a primary action button.
+
+### Loading States
+
+- **Skeleton** — gray boxes mimicking content shape (initial page loads)
+- **Spinner** — for triggered actions, not initial loads
+- **Progress** — multi-step or long operations
+- **Optimistic** — show expected result immediately, revert on error
+
+---
+
 ## Setup
 
 The `react-ts` scaffold template already includes the design system at `src/hailer/theme/`. **Do NOT copy from other projects.**
@@ -43,6 +120,15 @@ import { theme } from './hailer/theme/theme';
 - `bodyText` - Main text
 - `chakra-body-bg` - Page background
 
+**Background hierarchy:**
+- Page: `gray.50` or white
+- Card: white (with subtle shadow)
+- Hover: `gray.100`
+- Selected: `brand.50` or `blue.50`
+- Disabled: `gray.100` with `gray.400` text
+
+**Contrast:** 4.5:1 minimum for text (WCAG AA), 3:1 for large text and UI components.
+
 ---
 
 ## Buttons
@@ -110,6 +196,8 @@ import { HailerPlus, HailerSettings } from './hailer/theme/icons';
 <Text fontSize="sm" color="subtleText">Caption</Text>
 ```
 
+Text alignment: left-align body, center short headings/CTAs, right-align numbers in tables. Never justify body text.
+
 ---
 
 ## Spacing
@@ -137,6 +225,8 @@ import { HailerPlus, HailerSettings } from './hailer/theme/icons';
 
 **Selection controls:** Only green colorScheme for Checkbox, Radio, Switch.
 
+Labels above inputs (mobile-friendly). Group related fields in sections.
+
 ---
 
 ## Tables
@@ -153,7 +243,7 @@ import { HailerPlus, HailerSettings } from './hailer/theme/icons';
       </Tr>
     </Thead>
     <Tbody>
-      <Tr>
+      <Tr _hover={{ bg: 'gray.50' }}>
         <Td>Item</Td>
         <Td isNumeric>42</Td>
       </Tr>
@@ -162,6 +252,8 @@ import { HailerPlus, HailerSettings } from './hailer/theme/icons';
 </TableContainer>
 ```
 
+Responsive: hide secondary columns on mobile with `display={{ base: 'none', md: 'table-cell' }}`.
+
 ---
 
 ## Modals