@hailer/mcp 1.3.21 → 1.3.32

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

@@ -1,60 +1,155 @@
 ---
 name: hailer-app-builder
-description: Patterns for building Hailer apps with @hailer/app-sdk
-version: 1.3.1
+description: Core patterns for building Hailer apps with @hailer/app-sdk — load when building any app, reading activity data, writing field values, handling SDK versions, implementing real-time updates, or debugging common app errors
+version: 3.12.0
 triggers:
   - build app
   - hailer app
   - app sdk
 ---
 
-# Hailer App Builder Skill
+# Hailer App Builder
 
-Patterns and templates for building Hailer apps with @hailer/app-sdk.
+Core patterns and templates for building Hailer apps with `@hailer/app-sdk`. For UI components and icons, load `hailer-design-system`. For scaffolding, publishing, and deploy, load `create-and-publish-app` or `publish-hailer-app`. For canonical UI primitives (ConfirmDialog, SearchableSelect, DatePicker, hailerRest), load `hailer-app-primitives`.
 
 <build-philosophy>
 ## How to Build Fast: Correct Data First, Theme Does the Looks
 
-The goal of the first version is **showing the correct data the user asked for** — not a custom-designed UI. Get the data right; the user iterates on looks afterward. Two rules make apps both fast and good:
+1. **Spend your effort on the data layer.** Read real field/phase/workflow IDs from `workspace/enums.ts` + `fields.ts` (never guess, never use labels as keys). A dashboard showing the *wrong* numbers beautifully is a failure; correct numbers in plain components is a success.
 
-1. **Spend your effort on the data layer, because that's what's easy to get wrong.** Read the real field/phase/workflow IDs from `workspace/enums.ts` + `fields.ts` (never guess, never use labels as keys), fetch with the SDK, and read field values by ID. A dashboard that shows the *wrong* numbers beautifully is a failure; correct numbers in plain components is a success.
-
-2. **Do NOT hand-design UI or build a component library — the scaffold already installed the Hailer theme.** `main.tsx` wires `<ChakraProvider theme={hailerTheme}>`, so **every stock Chakra component is already on Hailer brand** (Nunito Sans, the full Hailer palette, light/dark via system) and there are **214 ready icons** in `src/hailer/theme/icons/`. Compose the UI from plain Chakra primitives — they look right for free:
-   - Layout: `Box`, `Flex`, `Grid`, `SimpleGrid`, `Stack`, `Container`
-   - Data: `Stat`/`StatLabel`/`StatNumber`/`StatHelpText` (stat cards), `Table`/`Thead`/`Tbody`/`Tr`/`Td`, `Card`/`CardHeader`/`CardBody`
+2. **Do NOT hand-design UI.** The scaffold wires `<ChakraProvider theme={hailerTheme}>` — every stock Chakra component is already on Hailer brand. Compose from plain Chakra primitives:
+   - Layout: `Box`, `Flex`, `Grid`, `SimpleGrid`, `Stack`
+   - Data: `Stat`/`StatLabel`/`StatNumber`, `Table`/`Thead`/`Tbody`/`Tr`/`Td`, `Card`/`CardBody`
    - Text/state: `Heading`, `Text`, `Badge`, `Tag`, `Spinner`, `Skeleton`, `Alert`
-   - Import icons like `import { HailerSearch } from './hailer/theme/icons/HailerSearch'`
 
-   Don't write custom CSS, custom color values, or bespoke styled components on the first pass. Reach for a Chakra component; it's already themed. The user refines the look later — your job is correct data in a clean themed shell.
+3. **Always handle three states** — loading (`Spinner`/`Skeleton`), empty (a `Text`, never a crash), and outside-Hailer (the app must render standalone).
 
-3. **Always handle the three states** — loading (`Spinner`/`Skeleton`), empty (a `Text`, never a crash), and outside-Hailer (the app must render standalone — never block on `inside`). Real data is async; assume it's missing first.
+4. **VERIFY data exists BEFORE building against it.** Check activity counts per phase for every workflow+phase you plan to fetch. After publishing, state what data the app should show so the user can confirm it matches.
+</build-philosophy>
 
-4. **The scaffold's package.json IS the dependency budget — do NOT `npm install` anything else.** The scaffold already ships everything a v1 app needs: `@chakra-ui/react` (+emotion) for UI, `chart.js` + `react-chartjs-2` for charts, `framer-motion` for animation AND drag gestures, `zustand` for state, `immer`, and `@hailer/app-sdk`. No dnd-kit, no other chart libs, no date libs, no component kits — external packages mean unreviewed bytes shipped into the workspace and a look that drifts off-theme. If the requested UX genuinely seems to need a new dependency, FIRST prefer the simpler themed version (e.g. a board moves items with buttons/menus + `hailer.activity.update`, or framer-motion drag), and if that truly won't do, ASK the user before installing anything.
+<version-check>
+## SDK Version Check (FIRST STEP)
 
-5. **VERIFY data exists BEFORE building against it, and AFTER publishing.** An app that renders its empty state on real data is NOT done — it's unverified. Before writing components: check activity counts per phase (MCP `list_activities` with `countOnly: true`, or `core_init`) for every workflow+phase you plan to fetch. If the phase you targeted is empty (e.g. zero matches in "Scheduled"), pick the phases that actually hold the data — don't guess from phase names. After publishing: state what data the app should show ("8 matches in Scheduled, 24 fans across 4 phases") so the user can confirm the live app matches. "Shipped, shows 'no data'" is a failed delivery unless the workspace genuinely has no data — and then say so explicitly.
-</build-philosophy>
+**Before writing any code, check `package.json` for the `@hailer/app-sdk` version.** The 1.x and 2.x APIs differ in parameter names and return types.
 
-<critical-rules>
-## CRITICAL: Scaffolding and Data Sources
+### Breaking Changes: v1 → v2
 
-**Scaffold with the exact non-interactive form, then prep it:**
-```
-npx @hailer/create-app <name> --template react-ts
-npx hailer-mcp prep-app <name>
+| Method | v1 (1.0.3) | v2 (2.0.0+) |
+|--------|-----------|-----------------|
+| `activity.create()` | `(processId, items[], opts?)` | `(workflowId, items[], opts?)` |
+| `user.list()` return | `{[key: string]: User}` object map | `User[]` array |
+| `app.config.update()` | `(appId, config)` | `(config, {appId?})` |
+| `product.isProductInstalled()` | `(id)` | `(productId, workspaceId)` |
+| `product.install()` | `(id)` | `(productId, workspaceId)` |
+| `product.list()` return | `Product[]` | `{products[], totalCount}` |
+| `permission.map()` | zero-arg `→ Promise<void>` | `({workspaceId?}?) → Promise<PermissionMap>` |
+
+### v2 Naming Inconsistency
+
+v2 renamed `processId` → `workflowId` in some methods but not others:
+- `activity.create(workflowId, ...)` — renamed
+- `activity.list(processId, ...)` — NOT renamed
+- `ui.activity.create(processId, ...)` — NOT renamed
+
+### User Type (v1 vs v2)
+
+- v1: `{ _id, firstname, lastname, email, lastSeen, defaultProfilepic, status?, managedUser?, removed? }` — rich shape
+- v2: `{ _id, firstname, lastname }` — minimal; profile metadata stripped
+
+### `Workflow.phases` is a map in ALL SDK versions
+
+`workflow.phases` is `{[phaseId: string]: WorkflowPhase}` in both v1 and v2. Calling `.find()` on it silently returns `undefined` every time.
+
+```typescript
+// WRONG — .find() silently returns undefined on a map
+const phase = workflow.phases.find(p => p._id === phaseId);
+
+// CORRECT — direct key lookup
+const phase = workflow.phases?.[phaseId];
 ```
-The name is POSITIONAL (not `--name`), the template must be valid (`react-ts`/`react`/`vanilla-ts`/`svelte-ts`/…, NOT `minimal`), and the dir must be fresh — that combination runs with zero prompts. A bare `npx @hailer/create-app`, a wrong `--name` flag, an invalid template, or piping input all drop into an interactive prompt that hangs the agent. `prep-app` then clears the scaffold's placeholder appId + fake author and fixes its `StoreSet` tsc error, so you skip those papercuts entirely. Scaffold fresh, never copy an existing app, never hand-create the structure. (Apps are script-only — no MCP scaffold tool exists.)
 
-**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
+### v2-Only Modules
+
+Don't import in 1.x apps: `payment`, `admin`, `metrics`, `workflow.install()`, `ui.workflow.function.edit()`.
+
+### v2 Renamed Types
+
+`HailerAppConfig` → `Config`, `HailerSettings` → `Settings`, `HailerSignal` → `Signal`, `HailerApiInfo` → `ApiInfo`
+
+### v2 Signal Changes
+
+`subscribedSignals` constructor option removed — v2 streams ALL signals. Drop the option; filter by `signal.name` in the callback.
+
+**v2 2.4.2 (runtime-verified):** activity signals use **dotted names** (`activity.update`, `activity.create`, `activity.delete`). Bare `'activity'` fires **0×**. Use prefix-match: `signal.name.startsWith('activity')`. Signal payload: `{ activityIds: string[], workflowId: string, phaseId: string }`.
+</version-check>
+
+<api-quick-index>
+## API Quick Index
+
+| Task | Method | Notes |
+|------|--------|-------|
+| List activities | `api.activity.list(wfId, phaseId, { limit, skip, filters, sortBy, sortOrder, includeUsers?, includeTeams?, includeHistory? }?)` | `search` does NOT exist in `ActivityListOptions` — only in `ActivityKanbanListOptions` |
+| Get one activity | `hailer.activity.get(activityId)` | Single arg in both v1 and v2 |
+| Create activities | `hailer.activity.create(wfId, items[], opts?)` | opts optional |
+| Update activities | `hailer.activity.update(items[], opts)` | Plain values, not {type,value} |
+| Delete activities | `hailer.activity.remove(activityIds[])` | Returns count |
+| Move to phase | `hailer.activity.update([{_id, phaseId}], {})` | No `.move()` method |
+| Kanban view | `hailer.activity.kanban.list(wfId, opts?)` | Grouped by phase |
+| Open activity sidebar | `hailer.ui.activity.open(id, opts?)` | |
+| Open create form | `hailer.ui.activity.create(wfId, opts?)` | v2.4.2+: **promise never settles on cancel** — see gotcha below |
+| Upload file | `hailer.file.upload(file, name, opts)` (SDK ≥2.4.x) / `hailer.ui.files.uploadFile(file, name, opts)` (legacy, deprecated in 2.4.x) | Returns fileId |
+| Show toast | `hailer.ui.snackbar.open(text, btn, ms?)` | Button is display-only, no action callback |
+| Get current user | `hailer.user.current()` | |
+
+> **Canonical read/write shape:**
+>
+> | Context | Shape |
+> |---------|-------|
+> | READ: REST/MCP `v3.activity.list` | `{ type: "text", value: "foo" }` |
+> | READ: app-sdk v2 | `"foo"` (raw value — no wrapper) |
+> | READ: app-sdk v1 | `{ value: "foo" }` |
+> | WRITE: app-sdk (create/update), MCP | `"foo"` (plain value — never wrap) |
+>
+> **The `{type,value}` object is READ-only.** Passing it to app-sdk write calls sends wrong data silently. Passing it to REST/MCP write calls is rejected with code 191.
+</api-quick-index>
+
+<rest-api-from-app>
+## Calling the REST API from an App (v2 only)
+
+`hailer.http.fetch` reaches the full authenticated `api.hailer.com` REST surface as the current user (v2 only; v1 apps lack `http.*`). See `hailer-app-primitives` → `hailerRest` for the canonical typed wrapper.
 
 ```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)
+const res = await hailer.http.fetch('https://api.hailer.com/api/v2/some.endpoint', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload),
+});
+// body is a RAW STRING — must JSON.parse manually
 ```
+
+- **URL must start with `https://api.hailer.com`** (`monolith.hailer.com` is private-DNS only — fails at DNS)
+- **Web:** allowlist is global — works out-of-the-box
+- **iOS:** `allowedUrls` is per-app, default empty → 400 "URL not allowed"
+- **`http.upload` is web-only** — absent on the iOS bridge
+
+When `hailer.request('x')` returns "Cannot find api endpoint", try `hailer.http.fetch` before concluding "can't":
+- **code 191** = handler reached, arg validation failed → endpoint IS reachable; fix the args
+- **code 7** = not exposed on the HTTP route → WS-only or truly blocked
+- **`messenger.*` is legacy no-version namespace** — use `/api/messenger.send` NOT `/api/v3/messenger.send`
+</rest-api-from-app>
+
+<critical-rules>
+## Scaffolding
+
+**When creating an app by copying a sibling app**, rewrite `index.html` `<title>` (and manifest `name`) immediately — stale titles cause wrong-app false positives during browser verification.
+
+**To create a new app:** `npx @hailer/create-app <name> --template react-ts` then `npx hailer-mcp prep-app <name>`. See `create-and-publish-app` skill for the full non-interactive form and gotchas.
+
+Use `mcp__hailer__manage_app` (`action:'create'`) only when you need a Hailer entry pointing to an already-deployed URL (no local files).
+
+**For project data (workflows, fields, phases):** Read `workspace/` TypeScript files directly. Do NOT use MCP tools for data structure queries.
+
+**Template portability — no insights:** A workflow used as a portable template must not depend on insights. Insights are not key-portable across workspaces. Template apps do client-side aggregation and ship an empty `workspace/insights.ts`.
 </critical-rules>
 
 <sdk-setup>
@@ -74,14 +169,11 @@ import { useHailer } from '@hailer/app-sdk';
 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>;
-
+  if (!inside) return <Text>Open this app inside Hailer</Text>;  // After hooks
   return <Box>...</Box>;
 }
 ```
@@ -90,36 +182,14 @@ function App() {
 <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 generates a buggy useHailer hook** — each component gets its own `useState`, so child pages see `inside: false` even when `App.tsx` sees `inside: true`.
 
-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:
+After scaffolding, ALWAYS replace `src/hailer/use-hailer.ts` with this shared-state implementation:
 
 ```typescript
 import { useSyncExternalStore } from 'react';
 import HailerApi from '@hailer/app-sdk';
 
-// Types
 interface HailerState {
   inside: boolean;
   hailer: ReturnType<typeof HailerApi> | null;
@@ -138,7 +208,6 @@ declare global {
   }
 }
 
-// Initialize store once on window
 function getStore() {
   if (!window.__hailerStore) {
     window.__hailerStore = {
@@ -148,26 +217,21 @@ function getStore() {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
       },
-      getSnapshot() {
-        return this.state;
-      },
+      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);
+      config: (cfg) => {
+        // v1: cfg.fields is a nested object { fieldKey: { value: ... } }
+        // v2: cfg IS the flat Record<string, string> directly — no .fields nesting
+        const flat = cfg?.fields ?? cfg ?? null;
+        window.__hailerStore!.setState({ inside: true, config: flat });
       },
+      error: (err) => console.error('Hailer SDK error:', err),
     });
     window.__hailerStore.setState({ hailer: api });
   }
@@ -180,1069 +244,449 @@ export default function useHailer() {
     store.subscribe.bind(store),
     store.getSnapshot.bind(store)
   );
-
-  return {
-    inside: state.inside,
-    hailer: state.hailer!,
-    config: state.config,
-  };
+  return { inside: state.inside, hailer: state.hailer!, config: state.config };
 }
 ```
 
-### Why This Works
+**Why:** Single store on `window` → all components share one source of truth. `useSyncExternalStore` is React 18's official pattern for external state.
 
-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
+### Scaffold tsc bugs — fix up front
 
-### Giuseppe Rule
+Freshly scaffolded apps carry tsc errors in `src/hailer/use-app.ts` — at minimum the `StoreSet` `replace?: boolean` → `replace?: false` fix (zustand 5). Apply immediately. `npx hailer-mcp prep-app <app-dir>` automates this fix.
 
-After scaffolding with `npx @hailer/create-app`, ALWAYS replace `src/hailer/use-hailer.ts` with the shared-state version above.
+A `vite-env.d.ts` containing an `import` becomes a module — ambient declarations stop being global; wrap them in `declare global { … }` to restore globals.
 </usehailer-fix>
 
-<sdk-api>
-## Activity API
+<onready-overfetch>
+## `onReady` / `useEffect([inside])` — Only Fetch What You Need
 
-```typescript
-// List activities from workflow phase
-const activities = await hailer.activity.list(workflowId, phaseId, options?);
+**Calling `hailer.workflow.list()`, `hailer.user.list()`, or `hailer.permission.map()` in `onReady` causes parent-frame spam and CORS errors when the app does not actually need those calls.**
 
-// Get single activity
-const activity = await hailer.activity.get(activityId);
+These calls fire translation-scope loads for each workflow, producing repeated `Error when listening to scope load: undefined` and `Failed to load translations for scope: misc` errors — re-triggered on every incoming signal.
 
-// 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
+A standalone or chat app that does not use workflow data should call only what it needs:
 
 ```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;
-}
+// Correct for a standalone/chat app
+useEffect(() => {
+  if (!inside) return;
+  hailer.user.current().then(u => setCurrentUser(u));
+}, [inside]);
 ```
+</onready-overfetch>
 
-### 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
-}
-```
+<sdk-api>
+## Field Keys — Default Build Pattern
 
-### Activity Interface
+**All new app builds reference workflows, phases, and fields by stable key → runtime hex via a `buildXxxSchema(workflows)` resolver.** Never hardcode hex IDs in app source. Activity IDs are the only exception.
 
 ```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 }>;
-  };
-}
+// src/constants/sales.ts — stable slugs, portable across tenants
+export const WORKFLOW_KEYS = { DEALS: 'sales-deals' } as const;
+export const PHASE_KEYS    = { OPEN: 'open', WON: 'won', LOST: 'lost' } as const;
+export const FIELD_KEYS    = { VALUE: 'dealValue', OWNER: 'owner' } as const;
 ```
 
-### 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!
-```
+**Missing-precondition rule:** Before building, verify: `grep -c '^\s*key:' workspace/*/fields.ts`. A workspace with zero keys means `auto_set_keys` never ran. Do not build a static hex table dressed as a resolver — escalate: "Run `mcp__hailer__auto_set_keys({ workflowId })` for each workflow first."
 
-**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,
-  })),
-  {}
-);
-```
+**Passing a workflow key directly to `hailer.activity.list()` returns code 127** ("Invalid process key or missing workspace id") — always pass resolved hex.
 
-### CRITICAL: activity.list() Requires Valid phaseId
+> **Resolver primitive-capture gotcha.** `FIELD_IDS` objects start as empty strings and are filled in at app boot. Any primitive string value copied at module-evaluation time stays `''` forever. Use object references (`FIELD_IDS.mu`) inside JSX/hooks, never copy a primitive leaf at module level.
 
-**Problem:** `hailer.activity.list(workflowId, '', options)` fails - empty phaseId not allowed.
+## Activity API
 
-**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();
+const activities = await hailer.activity.list(workflowId, phaseId);
+const activity = await hailer.activity.get(activityId);  // single arg, both v1 and v2
+const created = await hailer.activity.create(workflowId, activities[], options?);
+const count = await hailer.activity.update(activities[], options);
+const count = await hailer.activity.remove(activityIds[]);
 ```
 
-### Phase Selection
-
-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.
+### activity.list() — Pagination
 
-## Kanban API
+**Production limit cap (SUSPECT #1 FOR EMPTY DATA ON LOAD):** `hailer.activity.list()` silently returns `[]` on production when `limit` is too large — **no error thrown**, even with full admin permissions. `limit: 100` works, `limit: 1000` returns empty. Use `pageSize ≤ 200`.
 
 ```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;
+async function listAll(hailer: any, workflowId: string, phaseId: string, opts = {}, pageSize = 200) {
+  const all: any[] = [];
+  let skip = 0;
+  while (true) {
+    const page = await hailer.activity.list(workflowId, phaseId, { ...opts, limit: pageSize, skip });
+    all.push(...page);
+    if (page.length < pageSize) break;
+    skip += pageSize;
+    if (skip > 50000) break; // safety cap
+  }
+  return all;
 }
 ```
 
-## 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()`.
+### activity.list() Gotchas
 
-### File Upload
+- **Valid phaseId required:** Empty string `''` returns nothing.
+- **Don't assume phase names** — check `phases.ts` for exact strings (e.g. `"Uudet"` not `"New"`).
+- **Large `limit` silently returns `[]` on prod** — Keep `pageSize ≤ 200`.
+- **`returnFlat: true` is REST/MCP-only** — do NOT pass it to app-sdk. In v2 app-sdk, field values come back as raw values already; passing `returnFlat` silently has no effect.
+- **`activity.currentPhase` is unreliable from list/kanban paths.** Fix: stamp the queried phaseId: `all.push({ ...a, currentPhase: a.currentPhase || phaseId })`. When present, the value may be hex OR key — include entries for both in lookup maps.
 
+Multi-phase fetch:
 ```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 }
+const phaseResults = await Promise.all(
+  [PHASES.ACTIVE, PHASES.COMPLETED].map(phaseId =>
+    hailer.activity.list(workflowId, phaseId).catch(() => [])
+  )
 );
-
-// Then attach to activity on create:
-await hailer.activity.create(workflowId, [{ name: 'Doc' }], { fileIds: [fileId] });
+const all = phaseResults.flat();
 ```
 
-### 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);
-```
+**Phase fan-out across `phasesOrder` for archived rows.** When listing all rows including archived phases, iterate `workflowConfig.phasesOrder` rather than assuming one phase covers everything.
 
-### Insight UI
+### Phase Transitions
 
+No `hailer.activity.move()` — use update with phaseId:
 ```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
+await hailer.activity.update([{ _id: activityId, phaseId: newPhaseId }], {});
 ```
 
-## Insight API
+### hailer.activity.create() — phaseId is Optional
 
-```typescript
-// Get insight data (SQL query results)
-const data = await hailer.insight.data(insightId, { update?: true });
+`phaseId` in the options argument is optional. All these forms work:
+- `hailer.activity.create(wfId, [{name, fields, teamId}])` — options omitted
+- `hailer.activity.create(wfId, [{name, fields, teamId}], {})` — empty options
+- `hailer.activity.create(wfId, [{name, fields, teamId}], { phaseId: 'X' })` — phase-targeted
 
-// List all insights
-const insights = await hailer.insight.list();
+### hailer.ui.activity.create() vs hailer.activity.create()
 
-// Update insight
-const updated = await hailer.insight.update(insightId, partialUpdate);
-```
+`hailer.ui.activity.create(processId)` opens the native Hailer "new activity" sidebar.
 
-**Response structure:**
-```typescript
-interface InsightData {
-  columns: string[];
-  rows: any[][];
-}
+**Critical gotcha — cancel hangs the promise forever (v2.x ≥2.4.2).** If the user dismisses the form without saving, the awaited promise NEVER settles. Do NOT `await` it directly. Treat as fire-and-forget, or react to activity-created signals.
 
-interface InsightDoc {
-  _id: string;
-  name: string;
-  // ... other insight properties
-}
-```
+### Activity Object Field Names — v1 vs v2
 
-## Workflow API
+| Property | v1.x | v2.x (2.4.2 runtime) |
+|----------|------|------|
+| Field value read | `activity.fields?.[id]?.value` | `activity.fields?.[id]` (raw — `.value` wrapper gone) |
+| Team ID | (not on object) | `activity.teamId` (flat string) |
 
-```typescript
-// List all workflows
-const workflows = await hailer.workflow.list();
+Runtime-confirmed shape for `activity.get()` on @hailer/app-sdk **2.4.2**: `{_id, name, created, updated, sequence, priority, files, fields, followerIds, workflowId, phaseId, teamId}`.
 
-// Get single workflow with full schema
-const workflow = await hailer.workflow.get(workflowId);
-```
+**Silent failure pattern — v1→v2 migration:** Code that reads `activity.fields?.[id]?.value` compiles without errors in v2 but silently returns `undefined` everywhere.
 
-## User API
+### Editable Function Fields
 
-```typescript
-// Get current logged-in user
-const me = await hailer.user.current();
-// Returns: { _id, email, firstname, lastname, ... }
+A function field with `editable: true` is a valid write target via `hailer.activity.update()` — pass a plain scalar value. A stored value wins over the computed default.
 
-// Get specific user by ID
-const user = await hailer.user.get(userId);
+### hailer.insight.data() Option Types
 
-// 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();
-```
+Pass `{ update: true }` to force a fresh fetch. Passing `{}` (no `update` key) has been observed to hang silently in production.
 </sdk-api>
 
-<field-resolver>
-## Field Resolver Pattern
-
-Every scaffolded app includes `src/hailer/field-resolver.ts`. It resolves human-readable field keys to hex IDs at runtime.
-
-### Functions
-
-**`createFieldResolver(workflowFields)`** — low-level. Takes a workflow's `fields` map, returns a resolver function.
-
-**`useFieldResolver(workflows, workflowId)`** — hook-friendly wrapper. Takes `useApp().app.workflows` and a workflow ID.
-
-### How It Works
-
-- Pass a field **key** (e.g., `'matchDate'`) → resolves to hex ID at runtime
-- Pass a field **hex ID** (e.g., `'691ffdf84217e9e8434e5697'`) → returns as-is
-- Workflows without keys → passthrough, hex IDs still work
-
-### Usage
-
-```typescript
-import { useFieldResolver } from './hailer/field-resolver';
-import { useApp } from './hailer/use-app';
-
-const WORKFLOW_ID = '691ffdf84217e9e8434e56a5';
-const FIELD_KEYS = {
-  MATCH_DATE: 'matchDate',
-  HOME_TEAM: 'homeTeam',
-};
-
-function MyComponent() {
-  const { app } = useApp();
-  const f = useFieldResolver(app.workflows, WORKFLOW_ID);
-
-  // f() resolves keys to IDs — works with either
-  const date = activity.fields?.[f(FIELD_KEYS.MATCH_DATE)];
-  const team = activity.fields?.[f(FIELD_KEYS.HOME_TEAM)];
-}
-```
-
-### Key Points
-
-- Define field keys as constants (human-readable, portable across workspaces)
-- The resolver handles both keys and hex IDs — safe to pass either
-- Wait for workflow data before fetching activities — add the workflow to `useEffect` deps
-- `useApp().app.workflows` is loaded on init by the scaffold's `onReady` handler
-</field-resolver>
-
 <field-patterns>
 ## Extracting Field Values
 
 ```typescript
-// Fields are optional and nested
-interface Activity {
-  fields?: Record<string, { value: unknown }>;
-}
+// v1 — .value wrapper
+const amount = activity.fields?.[FIELD_ID]?.value as number;
+
+// v2 — raw value directly
+const amount = activity.fields?.[FIELD_ID] as number;
 
-// Safe extraction helper
+// Safe extraction helper (v1 shape)
 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();
+// ActivityLink — READ returns {_id, name} object, WRITE takes plain ID string
+interface ActivityLinkValue { _id: string; name: string; }
+const linked = activity.fields?.['fieldId']?.value as ActivityLinkValue;
 
-// Enum/Select field
-const status = activity.fields?.['fieldId']?.value as string;
+// Writing an ActivityLink field — plain ID only
+await hailer.activity.update([{
+  _id: activityId,
+  fields: { [LINK_FIELD_ID]: someActivityId },  // string, not {_id, name}
+}], {});
 
-// ActivityLink field (reference to another activity)
-// IMPORTANT: ActivityLink has nested structure, not direct values
-interface ActivityLinkValue {
-  _id: string;
-  name: string;
+// Defensive readLink helpers — activity.list returns activitylink as {_id,name} OR [{_id,name}]
+function readLinkId(v: unknown): string | undefined {
+  if (Array.isArray(v)) return (v[0] as any)?._id;
+  if (v && typeof v === 'object') return (v as any)._id;
+  if (typeof v === 'string') return v;
+  return undefined;
 }
-const linked = activity.fields?.['fieldId']?.value as ActivityLinkValue;
-const linkedId = linked?._id;      // Get linked activity ID
-const linkedName = linked?.name || 'Unknown';  // Get display name
+function readLinkName(v: unknown): string | undefined {
+  if (Array.isArray(v)) return (v[0] as any)?.name;
+  if (v && typeof v === 'object') return (v as any).name;
+  return undefined;
+}
+// Match linked activities by id, not name — names break silently on rename
 
 // User field
-interface UserValue {
-  _id: string;
-  firstname: string;
-  lastname: string;
-}
+interface UserValue { _id: string; firstname: string; lastname: string; }
 const user = activity.fields?.['fieldId']?.value as UserValue;
 const userName = user ? `${user.firstname} ${user.lastname}` : 'Unknown';
+
+// Date (timestamp)
+const formatted = new Date(activity.fields?.['fieldId']?.value as number).toLocaleDateString();
 ```
 
-## Finnish Date Parsing
+### React error #31 — range field rendered raw in JSX
 
-Insights and some fields return Finnish date strings (`dd.mm.yyyy`) instead of timestamps. These can't be sorted directly.
+**React error #31 = a `timerange` / `daterange` / `datetimerange` field value rendered directly in JSX.**
 
 ```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"
+function formatTimeRange(v: unknown): string {
+  if (!v) return '';
+  if (typeof v === 'object' && v !== null && 'start' in v && 'end' in v) {
+    const r = v as { start: number; end: number };
+    return `${new Date(r.start).toLocaleTimeString('fi-FI', { timeZone: 'Europe/Helsinki', hour: '2-digit', minute: '2-digit' })} – ${new Date(r.end).toLocaleTimeString('fi-FI', { timeZone: 'Europe/Helsinki', hour: '2-digit', minute: '2-digit' })}`;
+  }
+  return String(v);
 }
 ```
 
-**When to use:**
-- Insight data returns formatted dates (not timestamps)
-- Text fields containing dates
-- Displaying dates to Finnish users
-</field-patterns>
+## Write Field Formats (App-SDK)
 
-<component-templates>
-## Activity Table
+Pass plain values to `hailer.activity.create` / `hailer.activity.update` — no `{type, value}` or `{value}` wrappers.
 
 ```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>;
+// activity.create() format
+await hailer.activity.create(WORKFLOW_ID, [
+  {
+    name: 'Activity name',
+    fields: {
+      [FIELD_ID]: 'string value',
+      [NUMBER_FIELD]: 42,
+      [ACTIVITYLINK_FIELD]: 'linkedActId',  // plain string ID — not {_id, name}
+    },
+  },
+]);
 
-  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.update() format (null clears a field)
+await hailer.activity.update([
+  {
+    _id: 'activityId',
+    fields: {
+      [FIELD_ID]: 'new value',
+      [FIELD_TO_CLEAR]: null,
+    },
+    phaseId: 'newPhaseId',  // optional - move phase
+  },
+], {});
 ```
 
-## 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>
-  );
-}
-```
+**App-specific create() pitfalls:**
+- Passing single object instead of array — must always be an array
+- Passing `undefined` as options → `ValidationError "debug is not allowed"` — omit or pass `{}`
+- "Missing teams" error (code 127) → workflow needs `enablePreselectedTeam: true` + `preselectedTeam: { account: workspaceOwnerAccountId, team: teamId }`
+</field-patterns>
 
-## Stats Card
+<app-template>
+## Full App Skeleton
 
 ```typescript
-import { Stat, StatLabel, StatNumber, StatHelpText, Box, useColorModeValue } from '@chakra-ui/react';
+const WORKFLOW_ID = 'from_workflows.ts';
+const PHASE_ID = 'from_phases.ts';
+const FIELDS = { STATUS: 'fieldId' } as const;
 
-interface Props {
-  label: string;
-  value: number | string;
-  helpText?: string;
-}
+function App() {
+  const { inside, hailer } = useHailer();
+  const [activities, setActivities] = useState<Activity[]>([]);
+  const [loading, setLoading] = useState(true);
 
-function StatsCard({ label, value, helpText }: Props) {
-  const bg = useColorModeValue('white', 'gray.700');
+  useEffect(() => {
+    if (!inside) return;
+    hailer.activity.list(WORKFLOW_ID, PHASE_ID).then(setActivities).finally(() => setLoading(false));
+  }, [inside]);  // [inside] NOT [hailer]
 
+  if (!inside) return <Text>Open inside Hailer</Text>;
+  if (loading) return <Spinner />;
   return (
-    <Box p={4} bg={bg} borderRadius="md" shadow="sm">
-      <Stat>
-        <StatLabel>{label}</StatLabel>
-        <StatNumber>{value}</StatNumber>
-        {helpText && <StatHelpText>{helpText}</StatHelpText>}
-      </Stat>
+    <Box p={4} bg={useColorModeValue('gray.50', 'gray.800')} minH="100vh">
+      <Table variant="simple" size="sm">...</Table>
     </Box>
   );
 }
 ```
-</component-templates>
 
-<theme-patterns>
-## Hailer Theme Colors
+## App Version Display (REQUIRED)
 
-```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
+Every Hailer app must show its version number visually.
 
-**DON'T use these patterns:**
 ```typescript
-// ❌ WRONG - brand colors may not be defined in theme
-color="brand.600"
+// vite.config.ts — inject version at build time
+import { readFileSync } from 'node:fs';
+const manifest = JSON.parse(readFileSync('./public/manifest.json', 'utf-8'));
 
-// ❌ WRONG - hard-coded white fails on light backgrounds
-<Text color="white">Always white</Text>
+export default defineConfig({
+  define: { __APP_VERSION__: JSON.stringify(manifest.version) },
+});
 
-// ❌ WRONG - assumes light mode background
-<Badge bg="blue.100" color="blue.800">Status</Badge>
+// In App.tsx
+<Text fontSize="xs" color="gray.400" position="fixed" bottom={1} right={2}>
+  v{APP_VERSION}
+</Text>
 ```
+</app-template>
 
-**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>
+<reactive-data>
+## Reactive Data
 
-// ✅ 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>
-```
+After any create/update/delete/phase change, re-fetch data shown in the UI:
 
-**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' },
-  }
-}
+// Pattern 1: Refetch after mutation
+await hailer.activity.create(WORKFLOW_ID, [{ name, fields }], {});
+await loadActivities();
 
-// Usage - no useColorModeValue needed
-<Box bg="appBg"><Text color="textPrimary">Clean!</Text></Box>
+// Pattern 2: Refresh key (cross-component)
+const [refreshKey, setRefreshKey] = useState(0);
+<CreateForm onSuccess={() => setRefreshKey(k => k + 1)} />
 ```
 
-## Phase-Colored Badges and Bars
+### Tabs — Lazy Mount
 
-When displaying phase/status colors that need to work in both modes:
+**Chakra `<Tabs>` mounts all panels eagerly by default.** Without `isLazy`, every `<TabPanel>` fires effects in parallel even if the user never clicks them.
 
-```typescript
-import { useColorMode } from '@chakra-ui/react';
-
-// Helper for phase-colored elements
-function usePhaseColors(baseColor: string) {
-  const { colorMode } = useColorMode();
+```tsx
+<Tabs isLazy>
+  <TabPanels>
+    <TabPanel><HeavyDataTab /></TabPanel>
+    <TabPanel><AnotherTab /></TabPanel>
+  </TabPanels>
+</Tabs>
+```
+</reactive-data>
 
-  if (colorMode === 'light') {
-    return {
-      bg: `${baseColor}.100`,
-      color: `${baseColor}.800`,
-      borderColor: `${baseColor}.200`,
-    };
-  } else {
-    return {
-      bg: `${baseColor}.700`,
-      color: `${baseColor}.100`,
-      borderColor: `${baseColor}.600`,
-    };
-  }
-}
+<real-time>
+## Real-Time Updates via Signals
 
-// Usage
-function PhaseBadge({ phase, color }: { phase: string; color: string }) {
-  const colors = usePhaseColors(color);
+v1: `HailerSignal { sig, meta }` + `subscribedSignals` option. v2: `Signal { name, data }`, `subscribedSignals` removed — v2 streams all signals.
 
-  return (
-    <Badge bg={colors.bg} color={colors.color}>
-      {phase}
-    </Badge>
-  );
-}
+**v2 2.4.2:** dotted names (`activity.update`, `.create`, `.delete`). Bare `'activity'` fires 0×. Use prefix-match. Payload: `{ activityIds[], workflowId, phaseId }`.
 
-// Event bar with phase color
-function EventBar({ title, phaseColor }: { title: string; phaseColor: string }) {
-  const colors = usePhaseColors(phaseColor);
+**When to use:** Dashboards → signals. Forms → refetch after mutation.
 
-  return (
-    <Box
-      px={2}
-      py={1}
-      bg={colors.bg}
-      color={colors.color}
-      borderLeft="3px solid"
-      borderLeftColor={colors.borderColor}
-      borderRadius="sm"
-    >
-      {title}
-    </Box>
-  );
-}
-```
+### Debounced Reload (v2)
 
-**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',
-};
+const refreshTimerRef = useRef<NodeJS.Timeout | null>(null);
+const inFlightRef = useRef(false);
+signals: (signal: any) => {
+  if (!signal.name.startsWith('activity')) return;
+  const workflowId = signal.data?.process ?? signal.data?.processId ?? signal.data?.workflowId;
+  if (workflowId !== MY_WORKFLOW_ID) return;
+  if (inFlightRef.current) return;
+  if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+  refreshTimerRef.current = setTimeout(async () => {
+    inFlightRef.current = true;
+    try { await reload(); } finally { inFlightRef.current = false; }
+  }, 800);
+}
 ```
 
-</theme-patterns>
-
-<troubleshooting>
-## Workflow Permission Errors
-
-When SDK calls fail with permission/not-allowed errors, check **workflow configuration in Hailer** first.
-
-**Common symptoms:**
-- 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>
+**Replay storm guard:** skip signals arriving within ~3s of mount (`if (Date.now() - mountTimeRef.current < 3000) return`).
+**Skeleton gate:** `{loading && rows.length === 0 ? <Skeleton /> : <DataTable />}` — don't blank on background refresh.
+</real-time>
 
 <build-fixes>
 ## Common Build Errors
 
-### Cannot find module '@hailer/app-sdk'
-```typescript
-// WRONG
-import { useHailer } from '@hailer/app-sdk';
+| Error | Fix |
+|-------|-----|
+| `Cannot find module '@hailer/app-sdk'` | `import useHailer from './hailer/use-hailer'` |
+| `has no exported member 'useHailer'` | Use default import (not named) |
+| `fields possibly undefined` | `activity.fields?.[fieldId]?.value` |
+| Infinite re-render | `useEffect(..., [inside])` not `[hailer]` |
+| Hooks order error | All hooks before any early returns |
+| Hook in map/conditional | Move hook to component top level |
+| `activity.move is not a function` | Use `activity.update([{_id, phaseId}], {})` |
 
-// CORRECT
-import useHailer from './hailer/use-hailer';
-```
+### Routing
 
-### 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
-
-`activity.move()` does not exist. Use `activity.update([{ _id, phaseId }], {})` — see Phase Transitions in sdk-api.
-
-### Routing: HashRouter vs BrowserRouter
-
-**Most Hailer apps don't need routing at all.** Use state-based page switching:
+Most Hailer apps don't need routing — use state-based 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 /> },
-]);
+**Multi-page apps: use HashRouter, not BrowserRouter.** The static CDN at `apps.hailer.com/<ws>/<appId>/` serves only `index.html`.
 
-// URLs look like: yourapp.com/#/settings
-```
+### localStorage — scope per workspace+app
 
+`apps.hailer.com` is the shared origin for all deployed apps. Namespace every persisted key:
 ```typescript
-// ⚠️ AVOID BrowserRouter in iframe apps
-// Can cause "No routes matched location /index.html" errors
-// because iframe URL contains /index.html path
+const storageKey = (key: string) => `${workspaceId}.${appId}.${key}`;
+localStorage.setItem(storageKey('selectedStockId'), id);
 ```
 
-**When to use routing:**
-- Public apps with shareable URLs
-- Complex multi-section apps (like hailer-admin)
-- Apps where back button navigation matters
-</build-fixes>
+### `isAdmin` from `useApp` starts as `undefined`
 
-<sdk-crud>
-## SDK Create/Update Formats
+Guard `if (isAdmin === undefined) return <LoadingState/>` before any branch that gates on `isAdmin` — treating it as `false` before `permission.map()` completes causes admins to hit terminal branches before the flag flips.
 
-### activity.create() Format
+### `v3.app.public` always returns 403
 
-**Signature:** `hailer.activity.create(workflowId, activities[], options)`
+Endpoint is unimplemented in hailer-api. Workaround: settings workflow + public insight.
 
-**CRITICAL:** Takes array of activities, raw field values (not wrapped).
+### `vite build` does NOT type-check
 
-```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 }
-    },
-  },
-], {});
-```
+`npm run build` uses esbuild (transpile-only) — succeeds even when types are broken. Always run `npx tsc --noEmit` before declaring an app done.
 
-**Common mistakes:**
-- Passing single object instead of array
-- Wrapping field values in `{ value: ... }`
-- Passing `{ _id, name }` for activitylinks instead of just ID
+### Inline date-editor silently does nothing (self-blur trap)
 
-### activity.update() Format
+Native `<input type="date" autoFocus onBlur={commit}>` self-blurs on programmatic mount — the blur fires synchronously during `autoFocus`, calling the commit handler with an empty value. Fix: use `editorKind:'text'` so the cell falls through to a plain text input.
 
-**Signature:** `hailer.activity.update(activities[], options)`
+### Wizard / Multi-Step Form — Single Staging Surface Rule
 
-```typescript
-await hailer.activity.update([
-  {
-    _id: 'activityId',
-    name: 'New name',  // optional
-    fields: {
-      [FIELD_ID]: newValue,
-    },
-    phaseId: 'newPhaseId',  // optional - move to different phase
-  },
-], {});
-```
-</sdk-crud>
+A two-zone model (separate "review zone" + staged panel) causes silent empty-commit bugs — the clerk forgets to click "Add all" and the final create call receives empty rows.
 
-<file-structure>
-## Required Files
+**Rule: ONE staging surface.** When "Suggest rows" is clicked, push directly into the same `rows` state that the commit action reads from. Make the staged panel inline-editable.
+</build-fixes>
 
-```
-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)
-```
+<eslint-policy>
+## ESLint — Required Before Done
 
-## Constants File Pattern
+Every Hailer app must have working ESLint and pass lint before the app is considered done.
 
-```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;
+```bash
+npm run lint  # run before reporting done; lint errors block done
 ```
 
-</file-structure>
-
-<app-manifest>
-## App Manifest Configuration
-
-The `manifest.json` file in app root defines configurable settings exposed in Hailer UI.
-
-### config.fields Structure
-
+If the `lint` script is missing, add it:
 ```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;
+"scripts": { "lint": "eslint src --ext .ts,.tsx --max-warnings 0" }
 ```
+</eslint-policy>
 
-### 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)
+<file-handling>
+## File Handling
 
-For apps that run standalone (outside Hailer iframe) without authentication:
+A file-modifier text field (`modifier.file: true`) stores a JSON-stringified array of file IDs — parse it, don't read it as a single ID.
 
-```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);
+`hailer.file.get().data` is a full `data:` URI, not raw base64 — use it directly as an `<img src>`.
 
-// Public app config
-const config = await hailer.public.app.config();
+**`fileIds` only bind at `activity.create`.** There is no retroactive attach in app-sdk. Defer activity creation until files are ready. See `hailer-apps-pictures` for the canonical upload pattern.
+</file-handling>
 
-// Public products
-const products = await hailer.public.product.list(filter?, options?);
-const product = await hailer.public.product.get(productId);
-```
+<ios-compat>
+## iOS Compatibility — Default Target
 
-**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
+Build every app so it works on iOS unless a web-only capability is genuinely required.
 
-**Note:** Public APIs use keys (not IDs) and don't require authentication.
-</public-api>
+| Feature | Web | iOS |
+|---------|-----|-----|
+| `hailer.http.fetch('https://api.hailer.com/...')` | Works out-of-box | Requires `allowedUrls` to include `https://api.hailer.com` — default empty → 400 |
+| `hailer.http.upload` | Available | Absent — use `hailer.file.upload()` instead |
+| `ui.activity.editMultiple` | Available | Not supported |
+| `ui.insight.create/edit/delete/permission` | Available | Not supported |
 
-<sdk-reference>
-## SDK Type Definitions (For Edge Cases)
+When an app must use a web-only capability, state it explicitly: "This app will be web-only because it uses `http.upload`".
+</ios-compat>
 
-The skill covers common SDK methods. For less common APIs, read the type definitions in any Hailer app project:
+<vpc-reachability>
+## Apps Cannot Reach the Monolith
 
-```
-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)
-```
+Hailer apps run in the end user's browser, outside the microservice VPC. `monolith.hailer.com` is private-DNS only — `fetch('https://monolith.hailer.com/...')` fails at DNS resolution, not CORS.
 
-**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>
+Backend patterns when an app needs server logic: activity-write + phase webhook, or a dedicated internet-facing microservice.
+</vpc-reachability>