@hailer/mcp 1.1.12 → 1.1.13

package/.claude/skills/lsp-setup/SKILL.md

@@ -1,160 +0,0 @@
----
-name: lsp-setup
-description: How to set up LSP (Language Server Protocol) for Claude Code - enables code intelligence for Lars and other agents
-version: 1.0.0
-triggers:
-  - LSP not available
-  - typescript-language-server
-  - code intelligence setup
-  - Lars can't find unused code
----
-
-# LSP Setup for Claude Code
-
-LSP (Language Server Protocol) enables code intelligence features like go-to-definition, find-references, and accurate dead code detection.
-
-## Why LSP?
-
-Without LSP, agents like Lars must guess about code usage via grep/file reads. With LSP:
-- **Accurate dead code detection** - knows if exports are used elsewhere
-- **Type error detection** - without running compiler
-- **Find all references** - across entire codebase
-- **Go to definition** - jump to where symbols are defined
-
-## Requirements
-
-Three things needed for LSP to work:
-
-| Requirement | How to Check | How to Install |
-|-------------|--------------|----------------|
-| `ENABLE_LSP_TOOL=1` | Check `.claude/settings.json` | Add to env section |
-| `typescript-lsp` plugin | `claude plugin list` | `claude plugin install typescript-lsp@claude-plugins-official` |
-| Language server binary | `which typescript-language-server` | `npm install -g typescript-language-server typescript` |
-
-## Setup Steps
-
-### Step 1: Install the language server binary
-
-```bash
-npm install -g typescript-language-server typescript
-```
-
-Verify:
-```bash
-typescript-language-server --version
-# Should show version like: 5.1.3
-```
-
-### Step 2: Install Claude Code plugin
-
-```bash
-claude plugin install typescript-lsp@claude-plugins-official
-```
-
-Verify:
-```bash
-claude plugin list
-# Should show: typescript-lsp@claude-plugins-official ✔ enabled
-```
-
-### Step 3: Ensure settings.json has LSP enabled
-
-Check `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
-
-```json
-{
-  "env": {
-    "ENABLE_LSP_TOOL": "1"
-  }
-}
-```
-
-### Step 4: Restart Claude
-
-LSP plugin activates on Claude restart:
-```bash
-claude -c
-```
-
-### Step 5: Test
-
-Ask Lars to find unused code in a TypeScript file:
-```
-Find unused code in src/App.tsx
-```
-
-Or test LSP directly:
-```
-Use LSP documentSymbol on src/App.tsx
-```
-
-## Supported File Types
-
-The `typescript-lsp` plugin supports:
-- `.ts`, `.tsx` - TypeScript + React
-- `.js`, `.jsx` - JavaScript + React
-- `.mts`, `.cts` - TypeScript ES modules / CommonJS
-- `.mjs`, `.cjs` - JavaScript ES modules / CommonJS
-
-## LSP Operations Available
-
-| Operation | Purpose |
-|-----------|---------|
-| `documentSymbol` | List all symbols in a file |
-| `findReferences` | Find all usages of a symbol |
-| `goToDefinition` | Jump to where symbol is defined |
-| `hover` | Get type info and documentation |
-| `goToImplementation` | Find implementations of interface |
-| `incomingCalls` | What calls this function |
-| `outgoingCalls` | What this function calls |
-| `prepareCallHierarchy` | Get call hierarchy at position |
-
-## Agents That Use LSP
-
-| Agent | How They Use LSP |
-|-------|------------------|
-| **Lars** | Primary user - dead code, unused imports, type errors |
-| **Svetlana** | Type checking during code review (optional) |
-| **Giuseppe** | Verify code compiles before build (optional) |
-
-## Troubleshooting
-
-### "No LSP server available"
-
-1. Check binary is installed: `which typescript-language-server`
-2. Check plugin is installed: `claude plugin list`
-3. Restart Claude: `claude -c`
-
-### LSP times out on first query
-
-Normal - language server is indexing the project. Wait a few seconds and retry.
-
-### LSP works for .ts but not .tsx
-
-Check `typescript` is installed alongside `typescript-language-server`:
-```bash
-npm install -g typescript-language-server typescript
-```
-
-### "Executable not found in $PATH"
-
-The binary isn't in your PATH. Either:
-- Install globally: `npm install -g typescript-language-server`
-- Or add npm global bin to PATH: `export PATH="$PATH:$(npm bin -g)"`
-
-## Without LSP (Fallback)
-
-If LSP isn't available, agents can fall back to:
-
-```bash
-# Type errors
-npx tsc --noEmit 2>&1
-
-# Unused variables (requires eslint config)
-npx eslint --rule '@typescript-eslint/no-unused-vars: error' src/
-
-# Find references (grep-based, less accurate)
-grep -r "functionName" src/
-```
-
-This is less accurate but works without setup.

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

@@ -1,153 +0,0 @@
----
-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,72 +0,0 @@
----
-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
----
-
-# 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
-
-```typescript
-// Update insight - only changing public flag
-// sources parameter exists in schema but NOT needed for this update
-update_insight({
-  insightId: "abc123",
-  public: false
-  // sources: NOT included - omit entirely
-});
-
-// Update insight - changing sources
-update_insight({
-  insightId: "abc123",
-  sources: [{
-    name: 'tasks',
-    workflowId: 'wf123',
-    fields: [{ name: 'title', meta: 'name' }]
-  }]
-  // Include sources when actually updating them
-});
-```
-
-## Example 2: Wrong - Passing Empty Values
-
-```typescript
-// 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
-update_activity({
-  activityId: "xyz",
-  name: ""  // Error: name cannot be empty
-});
-```
-</examples>

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

@@ -1,244 +0,0 @@
----
-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
-
-The `publish_hailer_app` tool will SILENTLY FAIL if manifest.json is misconfigured.
-
-**YOU MUST validate these before calling publish_hailer_app:**
-
-1. Read `public/manifest.json` in the project
-2. Check `appId` exists and is 24 characters
-3. Check `version` exists and is NOT empty (e.g., "1.0.0")
-4. Check `versionDescription` exists and is NOT empty
-
-If ANY are missing/empty, FIX THEM FIRST before publishing.
-</critical>
-
-<validation-code>
-## Validation Steps (DO THIS FIRST)
-
-```
-1. Read({file_path: "{projectDir}/public/manifest.json"})
-
-2. Verify JSON contains:
-   - "appId": "24-char-id"        ← If missing: use create_app first
-   - "version": "1.0.0"           ← If empty: set to "1.0.0"
-   - "versionDescription": "..."  ← If empty: set to "Initial release"
-
-3. If any field missing/empty → Edit manifest.json to fix
-
-4. ONLY THEN call publish_hailer_app
-```
-</validation-code>
-
-<workflow>
-## Full Publishing Workflow
-
-### Step 1: Check if Production App Exists
-
-```javascript
-list_apps()
-```
-Look for your app with a `https://apps.hailer.com/...` URL (NOT localhost).
-
-### Step 2: Create Production App (if needed)
-
-If app doesn't exist or only has localhost URL:
-```javascript
-create_app({
-  name: "My App Name",
-  description: "What the app does"
-})
-```
-Returns new appId with production URL.
-
-### Step 3: Validate & Fix manifest.json
-
-Read the manifest:
-```javascript
-Read({file_path: "{projectDir}/public/manifest.json"})
-```
-
-Required structure:
-```json
-{
-  "appId": "695816e2ba1d8bef3af7e018",
-  "version": "1.0.0",
-  "versionDescription": "Initial production release"
-}
-```
-
-**If appId missing:** Add the ID from Step 2
-**If version empty:** Set to "1.0.0"
-**If versionDescription empty:** Set to "Initial release"
-
-### Step 4: Publish
-
-```javascript
-publish_hailer_app({
-  projectDirectory: "/path/to/app"
-})
-```
-
-### Step 5: Switch URL to Production
-
-`publish_hailer_app` uploads files but does NOT change the app URL. Switch it:
-```javascript
-update_app({
-  appId: "695816e2ba1d8bef3af7e018",
-  url: "https://apps.hailer.com/{workspaceId}/{appId}/"
-})
-```
-
-### Step 6: Verify
-
-```javascript
-list_apps()
-```
-Confirm URL is `https://apps.hailer.com/...` (not localhost).
-</workflow>
-
-<silent-failure>
-## Why Silent Failures Happen
-
-The SDK publish script requires `version` and `versionDescription` in manifest.json.
-If missing/empty, the tool returns "Success" but files are NOT uploaded.
-
-**Symptoms of silent failure:**
-- Tool says "App Published Successfully!"
-- But app URL is still `http://localhost:3000`
-- Or production URL returns 403/404
-
-**Always validate manifest BEFORE publishing.**
-</silent-failure>
-
-<dev-vs-prod>
-## Dev vs Production Apps
-
-| Type | URL | Created By | Can Publish To |
-|------|-----|------------|----------------|
-| 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
-
-**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>
-## Updating Published Apps
-
-1. Bump version in manifest.json:
-```json
-{
-  "version": "1.0.1",
-  "versionDescription": "Fixed data loading bug"
-}
-```
-
-2. Publish:
-```javascript
-publish_hailer_app({
-  projectDirectory: "/path/to/app"
-})
-```
-
-New version replaces old at same URL.
-</updating>
-
-<sharing>
-## Sharing Apps
-
-```javascript
-// Entire workspace
-add_app_member({ appId: "...", member: "network_{workspaceId}" })
-
-// Team
-add_app_member({ appId: "...", member: "team_{teamId}" })
-
-// User
-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
-
-- [ ] Production app exists (`create_app`, not scaffold)
-- [ ] 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>