@hailer/mcp 1.0.29 → 1.1.3

package/.claude/skills/mcp-direct-tools/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: mcp-direct-tools
+description: Reference for MCP tools not assigned to agents
+version: 1.0.0
+---
+
+# MCP Direct Tools
+
+<purpose>
+Reference for MCP tools not assigned to agents. Load this skill when user requests direct tool usage or needs capabilities not covered by standard agents.
+</purpose>
+
+---
+
+## When to Load This Skill
+
+- User asks "can you use the bug fixer tools?"
+- User needs capabilities not covered by agents
+- Direct MCP tool access requested
+- Debugging/testing MCP tools
+
+---
+
+## Bug Fixer Tools (16 tools)
+
+Automated bug fixing suite for Hailer apps. Use these for automated debugging workflows.
+
+### Discovery & Analysis
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_find_app` | Locate app by name | `{ appName }` |
+| `bug_fixer_analyze_bug` | Classify bug report | `{ bugReport, appId }` |
+
+### File Operations
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_list_files` | List project files | `{ appId, path? }` |
+| `bug_fixer_read_file` | Read file content | `{ appId, filePath }` |
+| `bug_fixer_write_file` | Modify file content | `{ appId, filePath, content }` |
+| `bug_fixer_apply_fix` | Apply code patch | `{ appId, filePath, patch }` |
+
+### Build & Test
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_run_build` | Execute build command | `{ appId }` |
+
+### Git Operations
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_git_status` | Check git status | `{ appId }` |
+| `bug_fixer_git_pull` | Fetch latest code | `{ appId }` |
+| `bug_fixer_git_commit` | Commit changes | `{ appId, message }` |
+| `bug_fixer_git_push` | Push to remote | `{ appId }` |
+| `bug_fixer_git_revert` | Undo changes | `{ appId }` |
+
+### Workflow Management
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_start_fix` | Begin fix workflow | `{ bugId, appId }` |
+| `bug_fixer_mark_declined` | Close as not-a-bug | `{ bugId, reason }` |
+| `bug_fixer_publish_fix` | Deploy to production | `{ appId, version }` |
+| `bug_fixer_retry_fix` | Attempt with new context | `{ bugId, newContext }` |
+
+### Bug Fixer Workflow
+
+```
+1. bug_fixer_find_app → Get app ID
+2. bug_fixer_analyze_bug → Classify issue
+3. bug_fixer_start_fix → Begin workflow
+4. bug_fixer_list_files → Find relevant files
+5. bug_fixer_read_file → Understand current code
+6. bug_fixer_write_file / bug_fixer_apply_fix → Make changes
+7. bug_fixer_run_build → Verify fix
+8. bug_fixer_git_commit → Save changes
+9. bug_fixer_publish_fix → Deploy
+```
+
+---
+
+## Insight Tools (Not in Viktor)
+
+Viktor uses `preview_insight` and `get_insight_data`. These additional tools are available:
+
+| Tool | Description | When to Use |
+|------|-------------|-------------|
+| `list_insights` | List all insights in workspace | Discovery, cleanup |
+| `update_insight` | Modify existing insight | Query changes |
+| `remove_insight` | Delete insight (NUCLEAR) | Cleanup |
+
+**Note:** SDK has equivalents via insights.ts push. Use SDK for version-controlled changes, MCP for quick fixes.
+
+---
+
+## Workflow Tools (PLAYGROUND/NUCLEAR)
+
+Direct workflow manipulation. Normally use Helga + SDK, but these exist for quick operations:
+
+| Tool | Description | Group |
+|------|-------------|-------|
+| `install_workflow` | Create workflow via MCP | PLAYGROUND |
+| `remove_workflow` | Delete workflow | NUCLEAR |
+| `update_workflow_field` | Modify field config | PLAYGROUND |
+| `update_workflow_phase` | Modify phase config | PLAYGROUND |
+| `test_function_field` | Test JS function | PLAYGROUND |
+
+**Warning:** NUCLEAR tools require `ENABLE_NUCLEAR_TOOLS=true` in MCP config.
+
+---
+
+## Tool Groups Reference
+
+| Group | Risk Level | Examples |
+|-------|------------|----------|
+| READ | Safe | list_activities, get_workflow_schema |
+| WRITE | Updates data | create_activity, add_discussion_message |
+| PLAYGROUND | Admin ops | install_workflow, update_workflow_field |
+| NUCLEAR | Destructive | remove_workflow, remove_app |
+| BOT_INTERNAL | Bots only | Not exposed to MCP clients |
+
+---
+
+## Usage Pattern
+
+When user requests direct tool usage:
+
+```
+User: "Use the bug fixer to fix this app"
+
+Orchestrator:
+1. Load this skill
+2. Call tools directly via mcp__hailer__<tool_name>
+3. Follow workflow patterns above
+4. Report results
+```
+
+---
+
+## Tools NOT Covered Here
+
+These are assigned to agents - use the agent instead:
+
+| Tool | Agent |
+|------|-------|
+| Activity CRUD | Dmitri |
+| Discussions | Yevgeni |
+| App scaffold/create | Giuseppe |
+| Insights preview/data | Viktor |
+| User search | Permissions Handler |

package/.claude/skills/optional-parameters/SKILL.md

@@ -1,14 +1,37 @@
 ---
 name: optional-parameters
 description: Omit optional parameters instead of passing empty values
+version: 1.0.0
 triggers: Tool error about empty array/string when parameter should be omitted
 ---
 
-<problem>
-Tool parameter is required in schema but should be OMITTED (not passed at all) when not needed, rather than passed as empty array/string.
-</problem>
+# Optional Parameters
+
+<purpose>
+Teach correct handling of optional tool parameters - OMIT them entirely when not needed, rather than passing empty arrays, strings, or null values.
+</purpose>
+
+<patterns>
+## Pattern 1: Omit vs Empty Value
+
+**Key distinction:**
+- **OMIT parameter**: Don't include it in the function call at all
+- **NOT same as empty value**: `[]`, `""`, `null`, `undefined` are NOT valid replacements for omission
+
+## Pattern 2: When to Omit
+
+- Updating insight public/name but NOT sources → omit sources
+- Updating activity field but NOT name → omit name
+- Any "required" schema parameter that's not relevant to current operation
+
+## Pattern 3: Rule of Thumb
+
+If you're not changing/using a value, OMIT the parameter entirely rather than passing empty/null.
+</patterns>
+
+<examples>
+## Example 1: Correct - Omitting Unused Parameters
 
-<correct>
 ```typescript
 // Update insight - only changing public flag
 // sources parameter exists in schema but NOT needed for this update
@@ -29,35 +52,21 @@ update_insight({
   // Include sources when actually updating them
 });
 ```
-</correct>
 
-<wrong>
+## Example 2: Wrong - Passing Empty Values
+
 ```typescript
-// ❌ WRONG - Passing empty array when parameter should be omitted
+// WRONG - Passing empty array when parameter should be omitted
 update_insight({
   insightId: "abc123",
   public: false,
   sources: []  // Error: sources must contain at least 1 items
 });
 
-// ❌ WRONG - Passing empty string
+// WRONG - Passing empty string
 update_activity({
   activityId: "xyz",
   name: ""  // Error: name cannot be empty
 });
 ```
-</wrong>
-
-<fix>
-**Key distinction:**
-- **OMIT parameter**: Don't include it in the function call at all
-- **NOT same as empty value**: `[]`, `""`, `null`, `undefined` are NOT valid replacements for omission
-
-**When to omit:**
-- Updating insight public/name but NOT sources → omit sources
-- Updating activity field but NOT name → omit name
-- Any "required" schema parameter that's not relevant to current operation
-
-**Rule of thumb:**
-If you're not changing/using a value, OMIT the parameter entirely rather than passing empty/null.
-</fix>
+</examples>

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

@@ -1,12 +1,27 @@
 ---
 name: publish-hailer-app
 description: Guide for publishing Hailer apps to production
+version: 1.2.0
+triggers:
+  - publish app
+  - deploy app
+  - production app
 ---
 
 # Publish Hailer App Skill
 
 Guide for publishing Hailer apps to production using MCP tools.
 
+<warning>
+## ⚠️ Publishing Requires Explicit User Request
+
+**Default is local development** — scaffold creates a dev app at `http://localhost:3000` automatically.
+
+**Only use this skill when the user explicitly asks to publish or deploy to production.**
+
+Before publishing: validate manifest.json (see below), then `publish_hailer_app`, then `update_app` to switch URL.
+</warning>
+
 <critical>
 ## MANDATORY: Validate Before Publishing
 
@@ -82,24 +97,23 @@ Required structure:
 
 ### Step 4: Publish
 
-**Option 1: Production Only**
 ```javascript
 publish_hailer_app({
   projectDirectory: "/path/to/app"
 })
 ```
 
-**Option 2: Production + Marketplace**
+### Step 5: Switch URL to Production
+
+`publish_hailer_app` uploads files but does NOT change the app URL. Switch it:
 ```javascript
-publish_hailer_app({
-  projectDirectory: "/path/to/app",
-  publishToMarket: true
+update_app({
+  appId: "695816e2ba1d8bef3af7e018",
+  url: "https://apps.hailer.com/{workspaceId}/{appId}/"
 })
 ```
 
-**IMPORTANT:** The `publishToMarket: true` parameter is REQUIRED to publish the app to the Hailer Marketplace. Without it, the app is published only to your production environment.
-
-### Step 5: Verify
+### Step 6: Verify
 
 ```javascript
 list_apps()
@@ -126,11 +140,15 @@ If missing/empty, the tool returns "Success" but files are NOT uploaded.
 
 | Type | URL | Created By | Can Publish To |
 |------|-----|------------|----------------|
-| Dev | `http://localhost:3000` | `scaffold_hailer_app` | NO - stays localhost |
-| Prod | `https://apps.hailer.com/...` | `create_app` | YES |
+| Dev | `http://localhost:3000` | `scaffold_hailer_app` or `create_app` | YES (after URL switch) |
+| Prod | `https://apps.hailer.com/{workspaceId}/{appId}/` | `create_app` | YES |
+
+**URL switching workflow:**
+1. During development: app URL is `http://localhost:3000/`
+2. When ready to publish: call `update_app` to set production URL: `https://apps.hailer.com/{workspaceId}/{appId}/`
+3. After publishing: URL stays as production
 
-**Key insight:** Dev apps (scaffolded) will ALWAYS use localhost.
-To deploy to production, create a NEW app with `create_app`.
+**Important:** `publish_hailer_app` uploads built files but does NOT automatically update the URL. You MUST also call `update_app` with the production URL format.
 </dev-vs-prod>
 
 <updating>
@@ -169,6 +187,49 @@ add_app_member({ appId: "...", member: "user_{userId}" })
 ```
 </sharing>
 
+<vite-config>
+## CRITICAL: Vite Base Path
+
+Vite apps MUST have `base: './'` in vite.config.ts for production deployment.
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  base: './',  // REQUIRED for production
+  // ... other config
+});
+```
+
+**Without this:**
+- Asset paths resolve to root domain instead of app folder
+- Production app returns 403/404 errors
+- Works in localhost but fails in production
+
+**Also verify:** The .tgz package must have files at `package/dist/` path structure.
+</vite-config>
+
+<cache-busting>
+## CRITICAL: Browser Cache for Published Apps
+
+Published Hailer apps serve stale versions from browser cache. Vite's hashed JS/CSS filenames handle asset cache-busting, but `index.html` itself needs no-cache headers.
+
+**Add these meta tags to `index.html` `<head>` before publishing:**
+
+```html
+<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" />
+<meta http-equiv="Pragma" content="no-cache" />
+<meta http-equiv="Expires" content="0" />
+```
+
+**Without these:**
+- Users see old app version after publish
+- Hard refresh (Ctrl+Shift+R) works but users won't know to do it
+- Particularly bad for bug fix deploys where users expect changes immediately
+
+**Why meta tags not server headers?**
+Hailer apps are served from `apps.hailer.com` static hosting - we can't control server headers. Meta tags are the only client-side cache control available.
+</cache-busting>
+
 <checklist>
 ## Pre-Publish Checklist
 
@@ -176,5 +237,8 @@ add_app_member({ appId: "...", member: "user_{userId}" })
 - [ ] manifest.json `appId` is 24 chars (not empty)
 - [ ] manifest.json `version` is set (e.g., "1.0.0")
 - [ ] manifest.json `versionDescription` is set (not empty)
+- [ ] vite.config.ts has `base: './'`
+- [ ] index.html has no-cache meta tags (see cache-busting section)
 - [ ] node_modules exists (dependencies installed)
+- [ ] After publish: `update_app` called to switch URL to production format
 </checklist>