@hailer/mcp 1.1.11 → 1.1.13

package/.claude/skills/chrome-mcp-reference/SKILL.md

@@ -1,370 +0,0 @@
-# Chrome DevTools MCP - Hailer App Testing
-
-<purpose>
-How to use Chrome DevTools MCP to navigate Hailer, open apps inside the Hailer iframe, and interact with app content for testing and debugging.
-</purpose>
-
-## Prerequisites
-
-- Chrome DevTools MCP server enabled (`/mcp-enable chrome-devtools`)
-- Chrome browser open with DevTools protocol enabled
-- Bot credentials in project `.env` file (see Bot Login section)
-
-## Quick Reference
-
-| Action | Tool | Key Detail |
-|--------|------|------------|
-| List browser tabs | `list_pages` | Find the Hailer tab |
-| Select a tab | `select_page` | Use `pageId` from list |
-| Navigate | `navigate_page` | Direct URL or back/forward |
-| Read page structure | `take_snapshot` | A11y tree with uids |
-| Click element | `click` | Use uid from snapshot |
-| Type text | `fill` | For inputs and selects |
-| Run JavaScript | `evaluate_script` | Custom DOM queries |
-| Take screenshot | `take_screenshot` | Visual verification |
-
----
-
-## Bot Login (API + Cookie Injection)
-
-Use a bot/service account instead of personal credentials. Each project has its own bot user. Authentication is done via API call, then the session token is injected into Chrome as a cookie.
-
-**IMPORTANT:** Always reset the session before switching between projects/bot users.
-
-### Environment Variables
-
-Store bot credentials in your project's `.env` file:
-```
-HAILER_BOT_EMAIL=bot@yourcompany.com
-HAILER_BOT_PASSWORD=your-bot-password
-```
-
-**Never commit `.env` to git.** Ensure `.gitignore` includes `.env`.
-
-### Complete Login Flow
-
-#### Step 1: Read credentials from project .env
-```
-Read({project_dir}/.env)
-→ Extract HAILER_BOT_EMAIL and HAILER_BOT_PASSWORD values
-```
-
-#### Step 2: Reset existing session (ALWAYS do this)
-```
-evaluate_script(function="() => {
-  // Clear cookies
-  document.cookie.split(';').forEach(c => {
-    const name = c.trim().split('=')[0];
-    document.cookie = name + '=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/';
-    document.cookie = name + '=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/; domain=.hailer.com';
-    document.cookie = name + '=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/; domain=app.hailer.com';
-  });
-  // Clear storage
-  localStorage.clear();
-  sessionStorage.clear();
-  return 'session reset';
-}")
-```
-
-#### Step 3: Get hlrkey via API
-```
-evaluate_script(function="async () => {
-  const res = await fetch('https://api.hailer.com/api/v3/login', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(['{BOT_EMAIL}', '{BOT_PASSWORD}'])
-  });
-  const data = await res.json();
-  return data;
-}")
-```
-
-The response contains the session token (`hlrkey`). Extract it from the response.
-
-#### Step 4: Inject hlrkey into browser
-```
-evaluate_script(function="() => {
-  const hlrkey = '{SESSION_TOKEN_FROM_STEP_3}';
-  // Set as cookie (what Hailer checks)
-  // URL-encode the hlrkey - it contains /, +, = characters
-  document.cookie = 'hlrkey=' + encodeURIComponent(hlrkey) + '; path=/; domain=.hailer.com; secure; samesite=lax';
-  // Set in localStorage (what the SPA reads)
-  localStorage.setItem('session_token', hlrkey);
-  return 'hlrkey set';
-}")
-```
-
-#### Step 5: Navigate and verify
-```
-navigate_page(type="url", url="https://app.hailer.com")
-wait_for(text="Aktiviteetit")  // or "Activities" for English workspaces
-take_snapshot
-→ Should show main Hailer navigation = logged in as bot
-```
-
-### Switching Between Projects
-
-Each project has its own bot user. When switching:
-1. **Always run Step 2** (reset session) first
-2. Read the new project's `.env` for credentials
-3. Run Steps 3-5 with new credentials
-
-### Session Persistence
-
-Once the hlrkey is set, the Chrome session persists across tool calls. Re-login needed when:
-- Browser tab closed or Chrome restarted
-- Session expires (typically several hours)
-- Switching to a different project's bot user
-
-To check if still logged in:
-```
-navigate_page(type="url", url="https://app.hailer.com")
-take_snapshot
-→ If "Sign in" heading visible → re-login needed
-→ If navigation bar visible → still authenticated
-```
-
----
-
-## Step-by-Step: Open a Hailer App
-
-### 1. Find and Select the Hailer Tab
-
-```
-list_pages
-→ Find page with url containing "app.hailer.com"
-→ select_page(pageId=N)
-```
-
-If no Hailer tab exists:
-```
-new_page(url="https://app.hailer.com")
-```
-
-### 2. Navigate to an App
-
-**Option A: Direct URL (fastest)**
-
-Every Hailer app has a URL pattern:
-```
-https://app.hailer.com/#/apps/{appId}
-```
-
-If you know the app ID:
-```
-navigate_page(type="url", url="https://app.hailer.com/#/apps/{appId}")
-```
-
-**Option B: Via Apps Menu (when you don't know the ID)**
-
-1. Take snapshot to find the navigation
-2. Look for the "Appit" (Apps) button in the bottom navigation bar
-3. Click it to open the dropdown menu
-4. Click the desired app name
-
-```
-take_snapshot
-→ Find: button "Appit" (typically in bottom navigation)
-→ click(uid="{appit_button_uid}")
-→ take_snapshot  (menu now visible with app names as menuitems)
-→ click(uid="{desired_app_uid}")
-```
-
-### 3. Wait for App to Load
-
-After clicking an app, the iframe loads. Wait for it:
-```
-wait_for(text="some text you expect in the app")
-```
-
-Or take a snapshot and check for the iframe:
-```
-take_snapshot
-→ Look for: Iframe "Hailer App"
-→ Inside it: RootWebArea with the app's content
-```
-
----
-
-## Hailer Page Structure
-
-The Hailer UI has this consistent structure:
-
-```
-RootWebArea "Hailer"
-├── button (notification badge)        # Top-left
-├── heading (current section name)     # Top bar - "Appit", "Aktiviteetit", etc.
-├── button "Avaa yleinen haku"         # Search button
-├── button "Avaa ilmoitukset"          # Notifications button
-│
-├── Iframe "Hailer App"               # ← APP CONTENT LIVES HERE
-│   └── RootWebArea "{App Title}"
-│       └── (app's own DOM tree)
-│
-└── navigation                        # Bottom navigation bar
-    ├── button "Aktiviteetit"         # Activities
-    ├── button "Tiedotteet"           # News
-    ├── button "Keskustelut"          # Discussions
-    ├── button "Kalenteri"            # Calendar
-    ├── button "Appit"               # Apps (click to see app list)
-    └── button "Käyttäjät"           # Users
-```
-
-**Key insight:** The bottom nav labels are in Finnish in Finnish workspaces. "Appit" = Apps.
-
----
-
-## Interacting with App Content Inside the Iframe
-
-Chrome DevTools MCP **automatically traverses iframes**. Elements inside the app iframe get their own uids and are fully interactive.
-
-### Reading App Content
-
-```
-take_snapshot
-→ Elements inside "Iframe 'Hailer App'" have normal uids
-→ Click, fill, hover them like any other element
-```
-
-With `verbose=true`, you get the full a11y tree including iframe internals:
-```
-take_snapshot(verbose=true)
-→ Shows complete DOM hierarchy including nested iframe elements
-```
-
-### Clicking App Elements
-
-Elements inside the iframe work just like any other:
-```
-click(uid="{element_inside_iframe}")
-```
-
-### Filling Form Fields Inside the App
-
-```
-fill(uid="{input_uid}", value="text to enter")
-```
-
-### Running JavaScript Inside the App Iframe
-
-To run JS specifically inside the iframe (not the parent Hailer shell):
-```
-evaluate_script(function="() => {
-  const iframe = document.querySelector('iframe');
-  return iframe?.contentDocument?.title;
-}")
-```
-
-**Note:** Cross-origin iframes block `contentDocument` access. For local dev apps (`localhost:3000`), this works because Hailer allows it via `allow="clipboard-read; clipboard-write"`. For production apps on different domains, use the snapshot/click approach instead.
-
----
-
-## Common Patterns
-
-### Pattern: Verify App Loaded Correctly
-
-```
-navigate_page(type="url", url="https://app.hailer.com/#/apps/{appId}")
-wait_for(text="{expected text in app}")
-take_snapshot
-→ Verify iframe contains expected content
-```
-
-### Pattern: Test App After Code Change
-
-```
-# After modifying app code and dev server hot-reloads:
-navigate_page(type="reload")
-wait_for(text="{expected text}")
-take_snapshot
-→ Verify changes are reflected
-```
-
-### Pattern: Check Console for Errors
-
-```
-list_console_messages(types=["error", "warn"])
-→ Shows errors from both Hailer shell and iframe app
-```
-
-### Pattern: Monitor Network Requests
-
-```
-list_network_requests(resourceTypes=["fetch", "xhr"])
-→ Shows API calls from the app to Hailer backend
-```
-
-### Pattern: Screenshot for Visual Verification
-
-```
-# Full page
-take_screenshot
-
-# Just the iframe app
-take_screenshot(uid="{iframe_uid}")
-```
-
-### Pattern: Get App ID from URL
-
-```
-evaluate_script(function="() => window.location.hash")
-→ "#/apps/6846bcbd9f213880bdf0f488"
-→ App ID is the part after /apps/
-```
-
-### Pattern: List All Available Apps
-
-```
-# Click the Apps menu button
-click(uid="{appit_button_uid}")
-take_snapshot
-→ Menu items are the available apps with their names
-```
-
----
-
-## Local Development Apps
-
-Local dev apps point their iframe to `http://localhost:3000`. The Hailer shell wraps them identically to production apps.
-
-| Property | Value |
-|----------|-------|
-| Iframe src | `http://localhost:3000/index.html` |
-| Iframe allow | `clipboard-read; clipboard-write` |
-| App SDK communication | `window.postMessage` between iframe and parent |
-| Hot reload | Works - Vite HMR updates inside iframe |
-
-To test a local dev app:
-1. Start the app dev server: `npm run dev` (in the app directory)
-2. Navigate to the app in Hailer (via URL or Apps menu)
-3. The iframe loads from localhost
-4. Changes hot-reload automatically
-
----
-
-## Troubleshooting
-
-| Issue | Fix |
-|-------|-----|
-| No Hailer tab | `new_page(url="https://app.hailer.com")` |
-| App shows blank iframe | Dev server not running - start `npm run dev` |
-| Can't find elements | Use `take_snapshot(verbose=true)` for full tree |
-| Iframe content not in snapshot | Wait for load: `wait_for(text="...")` |
-| Console errors from app | `list_console_messages(types=["error"])` |
-| Network requests failing | `list_network_requests` then `get_network_request(reqid=N)` |
-| Element click not working | Try `evaluate_script` with direct DOM manipulation |
-
----
-
-## Navigation Labels (Finnish ↔ English)
-
-| Finnish | English | What it does |
-|---------|---------|-------------|
-| Aktiviteetit | Activities | Main activity list |
-| Tiedotteet | News | News feed |
-| Keskustelut | Discussions | Chat/discussions |
-| Kalenteri | Calendar | Calendar view |
-| Appit | Apps | Apps menu (dropdown) |
-| Käyttäjät | Users | User management |
-| Avaa yleinen haku | Open search | Global search |
-| Avaa ilmoitukset | Open notifications | Notification panel |

package/.claude/skills/delegation-routing/SKILL.md

@@ -1,202 +0,0 @@
----
-name: delegation-routing
-description: Full agent routing table, chaining patterns, and delegation protocol
-version: 1.0.1
-triggers: which agent, routing, delegate, agent for, chain agents, multi-agent
----
-
-# Agent Delegation & Routing
-
-Load this skill when:
-- Routing is ambiguous ("is this Viktor or Alejandro?")
-- Planning multi-agent orchestration
-- User asks "which agent for X?"
-
----
-
-## Full Agent Routing Table
-
-### Data & Config
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Kenji** | LOCAL-FIRST data retrieval - reads workspace/ before API | Schema lookups, field lists, workflow metadata, activity counts |
-| **Dmitri** | Creates and updates Hailer activity data (WRITE-ONLY) | Single/bulk activity creation, updates, phase transitions |
-| **Helga** | Manages workspace config as infrastructure-as-code | Create workflows, add fields/phases, teams, groups, permissions. **Auto-spawns Alejandro** for name functions (always) + function fields (if PRD specifies) |
-
-### Apps & UI
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Giuseppe** | Builds Hailer apps with @hailer/app-sdk and Chakra UI | Full React/TypeScript app development with Hailer Design System |
-| **Marco** | Creates demo apps (non-functional) for validation | Fast prototyping, stakeholder demos before building production |
-| **UI Designer** | Designs app interfaces - layout, components, aesthetic | Design spec creation before Giuseppe builds (tone, signature element) |
-
-### Insights & Reports
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Viktor** | Creates SQL-like insights over workflow data | Reports, cross-workflow JOINs, aggregations, GROUP BY queries |
-| **Alejandro** | Creates calculated function fields AND workflow nameFunctions | Arithmetic, conditionals, date calculations, backlink aggregation, dynamic activity naming. *(Auto-spawned by Helga)* |
-
-### Documents
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Ingrid** | Document template specialist (PDF/CSV) | Create/update document templates with field mappings and pdfmake |
-
-### Integrations
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Igor** | Builds activity mover microservices | Phase cascade bots, trigger-based phase transitions |
-| **Ivan** | Builds automations in hailer-integration monolith | Webhooks, scheduled jobs, Netvisor/Procountor/Severa integrations |
-| **Zara** | Builds Zapier integrations for Hailer | Triggers, actions, Zap configurations (exports JSON for manual upload) |
-
-### Code Quality
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Svetlana** | Reviews code for bugs, security, best practices (READ-ONLY) | Pre-commit reviews, PR reviews, security audits |
-| **Lars** | LSP-powered code intelligence | Find dead code, unused imports, type errors via LSP only |
-| **Tanya** | Automated testing agent | Run vitest for functions, playwright for apps, verify builds |
-
-### Tools & API
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Gunther** | Builds MCP tools for Hailer MCP server | Create new MCP tools with Zod schemas in src/mcp/tools/ |
-| **Marcus** | Documents Hailer API endpoints | RPC/REST endpoint docs, Joi schema extraction, @hailer/cli examples |
-
-### Plugin System
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Ada** | Creates skills from failure patterns | Detect agent failures, create skills, update agent definitions |
-| **Builder** | Creates lean, token-efficient agents | New agents, refactor bloated agents, ensure SDK compatibility |
-| **Bjorn** | Audits codebase configuration | Verify CLAUDE.md accuracy, hook configs, workspace structure |
-| **Marketplace Publisher** | Publishes plugins to marketplace | Version check, publish plugins, create PRs, git workflows |
-| **Marketplace Reviewer** | AI-powered PR reviewer for marketplace | Validate schemas, check versions, auto-merge approved PRs |
-
-### Communication
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Yevgeni** | Handles Hailer discussions | Read threads, post messages, invite/remove members |
-| **Permissions Handler** | Manages Hailer app permissions | Grant/revoke user and team access to apps |
-
-### Utility
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| **Simple Writer** | Lightweight agent for basic code edits | ID replacements, string swaps, small fixes (faster than Giuseppe) |
-| **Code Simplifier** | Simplifies code for clarity and maintainability | After completing features, offer to run |
-| **Web Search** | Web research agent - searches and summarizes | Documentation lookups, current info, how-to questions (saves orchestrator context) |
-
----
-
-## Don't Confuse These
-
-| Agents | Distinction |
-|--------|-------------|
-| **Marco** vs **Giuseppe** | Marco = demo apps (non-functional mockups), Giuseppe = production apps |
-| **Igor** vs **Ivan** vs **Zara** | Igor = phase cascades (activity mover), Ivan = heavy/third-party integrations, Zara = Zapier only |
-| **Kenji** vs **Dmitri** | Kenji = READ data, Dmitri = WRITE data |
-| **Viktor** vs **Alejandro** | Viktor = SQL insights (read-only reports), Alejandro = function fields (calculated values stored on activities) |
-
----
-
-## Agent Chaining Patterns
-
-Some tasks require multiple agents in sequence. When agent returns `ready_to_push`, orchestrator runs the command automatically.
-
-### Add a New Field
-```
-Kenji → get IDs → Helga → add field (ready_to_push) → run push → Kenji → verify
-```
-
-### Create App with Workflow Data
-```
-Kenji → get structure → Viktor → create insight (if needed) → Giuseppe → build app → Tanya → test
-```
-
-### Add Calculated Field
-```
-Kenji → get field IDs → Alejandro → create function (ready_to_push) → run push → Tanya → test
-```
-
-### Create Activity
-```
-Kenji → get IDs → Dmitri → create activity
-```
-
-### Build Activity Mover
-```
-Kenji → get IDs → Helga → add metaData field (ready_to_push) → run push → Igor → build mover → Tanya → test
-```
-
-### Validate UI First
-```
-Kenji → get structure → Marco → demo app → (user validates) → Giuseppe → production app
-```
-
-### On Chain Failure
-- Kenji can't find ID → ask user to confirm name, suggest `/ws-pull`
-- Push fails → delegate to Bjorn for config audit
-- Tests fail → delegate to Svetlana for review
-
----
-
-## Delegation Protocol
-
-```
-Task(subagent_type="agent-name", prompt="JSON task spec", model="haiku|sonnet")
-```
-
-### Input Format
-```json
-{
-  "task": "action",
-  "context": {
-    "workflow_id": "...",
-    "field_ids": {}
-  },
-  "output": []
-}
-```
-
-### Output Format (JSON only, no prose)
-```json
-{
-  "status": "success|error|ready_to_push|needs_confirmation",
-  "result": {},
-  "summary": "max 50 chars"
-}
-```
-
-### Status Values
-| Status | Meaning | Orchestrator Action |
-|--------|---------|---------------------|
-| `success` | Task completed | Report to user |
-| `error` | Task failed | Report error, maybe retry |
-| `ready_to_push` | Files edited, needs push | Run commands in `commands` array |
-| `needs_confirmation` | Destructive action | Ask user, then run `safe_command` |
-
-### Flow
-Get IDs first (Kenji) → then pass to execution agents
-
----
-
-## Task Usage for Multi-Agent Work
-
-Use TaskCreate/TaskUpdate when orchestrating multiple agents:
-
-**Use tasks for:**
-- Multi-agent orchestration (Helga spawning Alejandro)
-- Multi-step PRD implementation
-- Work that might span multiple turns
-- Complex chains where tracking progress matters
-
-**Skip tasks for:**
-- Single-agent operations (quick field lookup, one activity creation)
-- Simple edits (ID replacements, string swaps)
-- Operations that complete in one turn
-
-**Example: Creating a workflow with calculated fields**
-```
-TaskCreate: "Create Employees workflow"
-TaskCreate: "Add name function to Employees" (blockedBy: workflow task)
-TaskCreate: "Add Tenure calculated field" (blockedBy: workflow task)
-```
-
-Mark tasks `in_progress` before delegating, `completed` after agent returns success.